BigQuery API 的 HTTP 状态和错误代码

本页面介绍了 BigQuery API 返回的 HTTP 状态代码和出错提示。您可以使用这些代码来排查和解决请求失败问题,并验证 API 行为。

如需详细了解非 API 错误、客户端库连接错误和 Cloud de Confiance 控制台错误,请参阅错误消息。

如需详细了解查询错误,请参阅排查查询错误。

如需详细了解流式插入错误,请参阅排查流式插入问题。

错误响应格式

BigQuery 为其 API 使用标准 HTTP 错误报告格式。成功的请求会返回 2xx 范围内的 HTTP 状态代码。失败的请求会返回 4xx 和 5xx 范围内的状态代码。需要重定向的请求会返回 3xx 范围内的状态代码。错误响应通常在响应正文中包含一个 JSON 文档,其中包含一个错误对象,该对象包含有关错误的信息。

在 BigQuery API 响应中,错误对象通常是以下各项之一:

本页状态代码表中的原因列会映射到 ErrorProto 对象中的 reason 属性。如果您使用 bq 命令行工具检查作业状态,请使用 --format=prettyjson 标志(例如 bq --format=prettyjson show -j <var>JOB_ID</var>)或 --apilog=stdout 查看错误对象及其 reason 属性。

下表介绍了可能出现在错误响应正文中的元素。应结合使用这些字段来帮助确定问题。 此外,下表中的示例值仅用于说明,并非所有可能值的详尽列表。

元素 说明
code HTTP 状态代码值,不含文本说明。

示例值包括:400(错误请求)、403(禁止访问)和 404(未找到)。
error 错误信息的容器。
errors 错误详情的容器。
错误。domain 错误的范围。示例值包括:global 和 usageLimits。
错误。location locationType 中导致错误的具体项。例如,如果您为某个参数指定了无效值,则 location 将是该参数的名称。

示例值包括:Authorization 和 project。
错误。locationType 导致错误的位置或请求部分。与 location 搭配使用,可精确定位错误。

示例值包括 header 和 parameter。
错误。message 错误说明。

示例值包括 Invalid argument、Access Denied 和 Not Found: Dataset myproject:foo。
错误。reason 错误原因的唯一标识符。

示例值包括 invalid、accessDenied 和 notFound。
message 错误说明。与 errors.message 相同。

HTTP 状态和错误代码

本部分包含 BigQuery API 的 HTTP 状态和错误代码的并非详尽无遗列表。1xx 信息代码和 2xx 成功代码会被省略。如需了解详情,请参阅 RFC 7231 §6、RFC 7232 §4、RFC 7233 §4、RFC 7235 §3 和 RFC 6585 中的“响应状态代码”。

400 - 请求无效

原因 HTTP 状态代码 说明 问题排查
badRequest 400

DML 语句尝试修改最近使用旧版 tabledata.insertAll API 流式插入且仍保留在表的流缓冲区中的行。系统会返回以下错误:UPDATE or DELETE statement over table project.dataset.table would affect rows in the streaming buffer, which is not supported。

迁移到 BigQuery Storage Write API (gRPC),等待几分钟让流式传输缓冲区刷新,或过滤语句以排除最近流式传输的行。如需了解详情,请参阅对具有流式传输缓冲区的表执行 DML 语句。

invalid 400

请求包含无效查询之外的无效输入,包括以下情况:

  • 架构不匹配 (Provided Schema does not match Table table)。
  • RECORD 列、文件或例程超出了 15 级嵌套限制 (Schema nested too deeply)。
  • 在作业期间被删除或过期的目标表 (Destination deleted/expired during operation)。

确保提供的架构与现有列和模式匹配,展平嵌套层级超过 15 层的结构(或将其存储为 JSON),并设置目标表过期时间,使其长于作业运行时间。如需了解每个子类型的步骤,请参阅排查无效输入和架构错误。

invalidQuery 400

SQL 查询因以下原因之一而无法通过验证或执行检查:

  • SQL 语法、标识符或数据类型无效。
  • 不满足功能选项或所需的分区过滤条件。
  • 超出了视图嵌套或分区输出限制。
  • 并发 DML 事务冲突(例如 Concurrent conflicting update to details)。

检查 [line:column] 位置是否存在 GoogleSQL 语法或类型不匹配问题,满足所需的 OPTIONS 或分区过滤条件,或回滚停滞的会话并重试冲突的 DML 作业。如需了解详情,请参阅无效查询错误和由于并发更新而导致事务中止。

jobBackendError 400

在 jobs.query 或 jobs.getQueryResults 中,系统创建了一个作业,但该作业在执行期间失败,并显示 backendError。错误返回:The job encountered an error during execution. Retrying the job may solve the problem.

使用截断指数退避算法,通过新的 jobId 重试作业,确保客户端重试逻辑除了处理 5xx 代码之外,还处理 HTTP 400 响应。如需了解详情,请参阅排查 jobBackendError 和 jobInternalError 错误。

jobInternalError 400

在 jobs.query 或 jobs.getQueryResults 中,作业已创建,但在执行期间因内部错误而失败。错误返回:The job encountered an internal error during execution and was unable to complete.

使用截断指数退避算法,通过新的 jobId 重试作业。如需了解详情,请参阅排查 jobBackendError 和 jobInternalError 错误。

preconditionFailed 400

未满足请求前提条件,包括以下情况:

  • 元数据更新期间 If-Match ETag 不匹配。
  • 缺少组织政策要求的 CMEK 加密密钥。
  • 标准版不支持的功能。
  • 在企业 Plus 版主要预留之外对故障切换数据集进行写入。
  • 针对具有待处理 upsert 的 CDC 基表的具体化视图查询。

在重试之前,请提取当前资源 etag,指定所需的 Cloud Key Management Service 密钥,在企业版或企业 Plus 版预留中运行工作负载,或等待几分钟,让待处理的 CDC upsert 应用。如需了解每个子类型的步骤,请参阅请求前提条件失败。

resourceInUse 400

删除请求的目标资源仍处于活跃状态或已填充:

  • 仍包含表、视图或例程的数据集。
  • 仍处于待处理或运行状态的作业。

错误返回:resource_type resource_id is still in use。

在删除数据集之前清空数据集(或设置 deleteContents=true、运行 bq rm -r -f -d 或执行 DROP SCHEMA IF EXISTS dataset_name CASCADE),或者在删除作业元数据之前等待活跃作业完成或取消该作业。如需了解详情,请参阅资源仍在使用中。

resourcesExceeded 400

作业在以下任一领域超出了执行资源限制:

  • 每个表的 DML 并发队列或会话并发限制。
  • 工作器、UDF、Shuffle 或机器学习模型内存预算。
  • 表分区(10,000 个分区)或输出列限制。
  • Cloud Key Management Service CMEK 请求速率、流式读取或跨区域数据传输。
  • 查询规划复杂度限制。

错误返回:Resources exceeded during query execution: details。

简化查询、批量执行 DML 操作、减少扫描的列或分区、避免在同一会话中运行并发作业,或为 Shuffle 密集型工作负载预配专用槽容量。如需了解每个子类型的步骤,请参阅排查资源超出限制的问题和查询超出内存资源。

storageUnusable 400

由于服务侧存储问题,保存表数据的内部 BigQuery 存储空间暂时不可用。错误返回: Storage of resource_id is unusable because reason.

使用截断指数退避算法重试作业。如需了解详情,请参阅表存储空间无法使用。

streamingDataUnavailable 400

写入优化存储空间中最近流式传输的数据暂时无法供读取作业使用。错误返回:Job failed because streaming data from table_source is temporarily unavailable. Retrying the job may solve the problem.

使用截断指数退避算法,通过新的 jobId 重试作业,确保客户端重试逻辑能够处理 HTTP 400 响应。如需了解详情,请参阅流式传输数据暂时不可用。

tableUnavailable 400

BigQuery 无法读取其不管理数据的表,包括以下情况:

  • 提取 Apache Iceberg 或 Delta Lake 表架构超时。
  • Hive 分区外部表没有分区键。
  • Google 管理的后备表暂时不可用。

使用截断指数退避算法重试架构提取或后备表超时,或者验证 key=value Cloud Storage URI 路径,并使用至少一个分区键重新创建 Hive 分区外部表。如需了解详情,请参阅外部表或后备表不可用。

userOwnedResourceError 400

当 BigQuery 访问您拥有的外部资源时,该资源会返回错误。系统会返回以下错误:Error when accessing a user-owned external resource_type resource resource_name. The resource provided error: external_error。

检查错误消息中的 resource_type 和 resource_name,以确定外部资源,并解决 external_error 中报告的底层错误。如需了解详情,请参阅用户拥有的外部资源错误。

vortexDataUnavailable 400

最近使用 BigQuery Storage Write API (gRPC) 流式传输到写入优化存储空间的数据暂时无法用于查询。错误返回:Job failed because vortex streaming data from table_source is temporarily unavailable. Retrying the job may solve the problem.

使用截断指数退避算法,通过新的 jobId 重试查询作业,确保客户端重试逻辑能够处理 HTTP 400 响应。如需了解详情,请参阅流式传输数据暂时不可用。

billingTierLimitExceeded 400

按需查询超出了每个扫描数据限制的最大 CPU 使用量。错误返回:Query exceeded resource limits. This query used cpu_seconds_used CPU seconds but would charge only analysis_megabytes_billed M Analysis bytes... cpu_seconds_used CPU seconds were used, and this query must use less than cpu_seconds_limit CPU seconds.

重构 SQL 以移除意外的笛卡尔积、不精确的联接、未分区的窗口函数或繁重的 JavaScript UDF,或者切换到基于容量(槽)的价格。如需了解详情,请参阅查询超出 CPU 资源和避免 SQL 反模式。

bytesBilledLimitExceeded 400

在执行开始之前,查询的执行前上限字节数估算值超过了 maximumBytesBilled。错误返回:Query exceeded limit for bytes billed: limit_bytes. required_bytes or higher required.

通过试运行预览估算的字节数,仅选择所需的列,并对分区列进行过滤,以减少处理的数据量,或将 maximumBytesBilled 提高到至少 required_bytes。如需了解详情,请参阅查询超出了计费字节数上限。

jobRateLimitExceeded 400

在 jobs.query 或 jobs.getQueryResults 中,作业会因以下原因之一而失败:

  • 作业在执行期间超出了速率限制 (Job exceeded rate limits: Your scope exceeded quota for quota_metric...)。
  • 由于已达到查询队列并发数或连续查询槽数上限(例如 Query was not admitted as the maximum concurrency has been reached...),因此查询未被接纳。

减少并发提交(或对持续查询使用批量优先级或槽自动扩缩),然后使用截断指数退避算法,通过新的 jobId 重试作业。如需了解详情,请参阅作业超出了速率限制和查询准入被拒。

timeout 400

操作超出其执行时间限制,包括以下情况:

  • 查询或试运行超出了 6 小时的执行限制。
  • 多语句查询中的子作业超时。
  • 外部表架构自动检测超时。

对分区列或聚簇列进行过滤,并将复杂查询或多语句查询拆分为较小的阶段,或者在创建外部表时指定显式架构和更窄的源 URI。如需了解详情,请参阅查询超出执行时间限制和排查配额和限制错误。

invalidUser 400

计划查询配置了无效的用户凭据。

刷新计划查询的用户凭证。如需了解详情,请参阅安排查询。

required 400

执行前缺少必需的输入:

  • 未提供 API 请求载荷或网址中的必填字段。
  • 客户端库中必需的配置对象为空或未分配。

错误返回:Required parameter is missing: parameter_name。

在 BigQuery API 参考文档或客户端库文档中验证所需的请求正文和查询参数,并在调用 API 之前检查配置对象。如需了解详情,请参阅缺少必需的参数。

401 - 未经授权

以下是如果您的请求缺少有效的身份验证凭证,您会收到的错误响应示例。

401 Unauthorized

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "unauthenticated",
        "message": "Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential."
      }
    ],
    "code": 401,
    "message": "Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential.",
    "status": "UNAUTHENTICATED"
  }
}
原因 HTTP 状态代码 说明 问题排查
unauthenticated 401

请求的身份验证失败,原因如下:

  • 请求缺少有效的身份验证凭证,或使用了过期的 OAuth 2.0 访问令牌。
  • 缺少最终用户凭据或服务账号模拟权限。
  • 来电者的用户账号受到限制或已被删除。

刷新您的 OAuth 或应用默认凭据,在以服务账号身份运行或模拟服务账号时授予 roles/iam.serviceAccountUser 或 roles/iam.serviceAccountTokenCreator,或者与管理员联系以恢复受限账号。如需了解详情,请参阅排查未经身份验证的错误。

403 - Forbidden

以下是您在无权访问所请求的资源时收到的错误响应示例。

403 Forbidden

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "accessDenied",
        "message": "Access Denied: Dataset myproject:mydataset: User does not have bigquery.datasets.get permission in project myproject."
      }
    ],
    "code": 403,
    "message": "Access Denied: Dataset myproject:mydataset: User does not have bigquery.datasets.get permission in project myproject."
  }
}
原因 HTTP 状态代码 说明 问题排查
responseTooLarge 403

查询或表读取响应通过以下方式之一超出大小限制:

错误返回:Response too large to return. details。

指定目标表(并将 configuration.query.allowLargeResults 设置为 true,以使用旧版 SQL)、移除 ORDER BY 或添加 LIMIT,或者使用 BigQuery Storage Read API 或 EXPORT DATA 读取大型行。如需了解详情,请参阅查询响应过大和超出单行响应大小限制。

apiLimitExceeded 403

请求超出了以下 API 或元数据限制之一:

  • 每分钟 API 请求速率限制。
  • 表或政策元数据评估配额。
  • 跨区域数据集副本创建限制 (Cannot add more than limit replicas for a region within window day(s))。

错误返回:API limit exceeded: details。

使用截断指数退避算法重试失败的请求,批量加载和读取,简化精细的每表 IAM 或行级安全政策,并在添加数据集副本之前等待滚动窗口。如需了解详情,请参阅 API 速率和元数据评估限制错误以及跨区域数据集副本创建限制错误。

quotaExceeded 403

您的项目超出了以下用量配额之一:

系统会返回以下错误:Quota exceeded: Your scope exceeded quota for quota_metric. For more information, see https://cloud.google.com/bigquery/docs/troubleshoot-quotas。

检查错误 message 以确定超出的配额,优化高扫描查询或从沙盒升级,或在配额页面上调整自定义配额。如需了解详情,请参阅自定义每日查询配额错误。

rateLimitExceeded 403

请求因以下速率或并发限制之一而被拒绝:

  • 短期 API 或查询作业速率限制 (Exceeded rate limits: too many quota_metric for this scope...)。
  • 查询队列并发或持续查询预留槽限制(例如 Query was not admitted as the maximum concurrency has been reached...)。

降低请求速率,并使用截断指数退避算法重试,或以批量优先级运行非紧急查询,并调整预留并发或槽自动扩缩。如需了解详情,请参阅排查配额和限制错误以及查询准入被拒。

accessDenied 403

由于以下原因之一,对 BigQuery 资源的访问被拒:

  • 主账号缺少对目标项目、数据集或表的必要 IAM 权限。
  • 授权视图、行级访问权限政策或列级政策标记会限制访问权限。
  • 缺少 Cloud Key Management Service CMEK 权限或外部数据源权限。

错误返回:Access Denied: resource_type resource_id: details。

检查 Cloud Audit Logs (protoPayload.authorizationInfo) 和 Policy Analyzer,找出缺少的权限,并授予权限最小的预定义 BigQuery 角色。如需了解详情,请参阅排查常见的“拒绝访问”场景。

policyViolation 403

安全边界或组织政策阻止了请求:

  • VPC Service Controls 边界会限制访问(包括 VPC-SC 项目中的 Google 云端硬盘导出或外部表)。
  • 组织政策限制条件(例如 constraints/gcp.resourceLocations)不允许执行该操作。

按 vpcServiceControlsUniqueIdentifier Logs Explorer 过滤,并检查违规分析器,使用边界内的 Cloud Storage 存储桶导出或加载数据,或选择组织政策限制条件允许的区域。如需了解详情,请参阅排查违规错误。

billingNotEnabled 403

项目缺少所请求操作的有效结算信息:

  • 此项目尚未启用结算功能。
  • 该项目在 BigQuery 沙盒中运行,其中的表、视图和分区会在 60 天 (expiration time must be less than 60 days) 后过期。

错误返回:Billing has not been enabled for this project. Enable billing at https://console.cloud.s3nscloud.fr/billing. details。

在 Cloud de Confiance 控制台中为项目启用结算功能,以从 BigQuery 沙盒升级,然后更新表、视图和分区的默认有效期。如需了解详情,请参阅未为项目启用结算功能。

blocked 403

BigQuery 暂时将尝试的操作添加到拒绝清单中,以防止服务中断。错误返回:Request was blocked to protect the system's operation. Please contact support at https://cloud.google.com/support.

联系 Cloud Customer Care,并提供确切的时间戳、项目 ID 和 BigQuery 作业 ID,以便调查管理缓解规则。如需了解详情,请参阅请求被屏蔽,以保护系统运行。

termsOfServiceNotAccepted 403

项目尚未接受《BigQuery 服务条款》。错误返回:BigQuery Terms of Service have not been accepted。

登录 Cloud de Confiance 控制台,在欢迎页面上选择您所在的国家/地区并选中“服务条款”复选框(如果系统提示),然后点击同意并继续。如需了解详情,请参阅未接受 BigQuery 服务条款。

404 - 未找到

以下是您尝试检索不存在的数据集或资源时收到的错误响应示例。

404 Not Found

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "notFound",
        "message": "Not Found: Dataset myproject:foo"
      }
    ],
    "code": 404,
    "message": "Not Found: Dataset myproject:foo"
  }
}
原因 HTTP 状态代码 说明 问题排查
notFound 404

由于以下原因之一,无法找到请求的资源:

  • 目标数据集、表或作业不存在或已过期。
  • 外部 Cloud Storage 或 Google 云端硬盘文件 URI 不存在。
  • 请求位置与数据集或作业位置不匹配。

错误返回:Not found: resource_type resource_id。

验证区分大小写的确切项目、数据集和表标识符及位置,在时间旅行窗口内恢复已删除的表,重新运行缓存结果表已过期的查询,或确认外部 Cloud Storage 或 Google 云端硬盘文件是否存在。如需了解详情,请参阅未找到表、未找到位置和未找到作业。

409 — Conflict

以下是您在尝试创建已存在的资源时收到的错误响应示例。

409 Conflict

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "duplicate",
        "message": "Already Exists: Dataset myproject:mydataset"
      }
    ],
    "code": 409,
    "message": "Already Exists: Dataset myproject:mydataset"
  }
}
原因 HTTP 状态代码 说明 问题排查
abortd 409

操作因并发修改或冲突而停止(返回的原因拼写为 abortd)。

在冲突操作完成后,使用截断指数退避算法重试该操作,或在重试之前回滚已停止的多语句事务。如需了解详情,请参阅操作已中止。

duplicate 409

请求会通过以下方式之一与现有资源发生冲突:

  • 创建已存在的数据集、表或作业资源。
  • 在目标表已存在的情况下,运行 writeDisposition 设置为 WRITE_EMPTY 的作业。

错误返回:Already Exists: resource_type resource_id。

请使用其他资源名称,在 DDL 语句中使用 IF NOT EXISTS 或 CREATE OR REPLACE,将 writeDisposition 更改为 WRITE_APPEND 或 WRITE_TRUNCATE,或者让 BigQuery 生成随机 jobId。如需了解每个子类型的步骤,请参阅资源已存在。

499 - 客户端关闭了请求

原因 HTTP 状态代码 说明 问题排查
stopped 499

作业在完成之前停止,原因如下(轮询 jobs.get 会返回 HTTP 200 和 reason: stopped):

  • 调用方明确取消作业 (User requested cancellation)。
  • 作业超出了配置的执行或队列超时时间(Job timed out after duration 或 Job timed out in the queue after duration)。

错误返回:Job execution was cancelled: details。

增加 configuration.jobTimeoutMs 或项目队列超时选项(或优化查询运行时和并发),或查看 Cloud Audit Logs 以了解 jobservice.cancel 调用。如需了解每个子类型的步骤,请参阅作业执行已取消。

500 - 内部服务器错误

原因 HTTP 状态代码 说明 问题排查
internalError 500

BigQuery 内部发生错误。错误返回: An internal error occurred and the request could not be completed.

根据 BigQuery 服务等级协议中的退避要求等待,然后使用截断指数退避算法重试,或使用预留来降低暂时性错误的频率。如需了解详情,请参阅排查 internalError 错误。

501 - 未实现

原因 HTTP 状态代码 说明 问题排查
notImplemented 501

请求尝试对目标资源使用未实现的功能或操作,例如:

  • 复制具有非代管式存储类型的表。
  • 运行不受支持的 ALTER SEARCH INDEX 选项。

错误返回:Not Implemented: details。

使用 CREATE TABLE destination_table AS SELECT * FROM source_table 实体化不受支持的表复制来源,或使用 DROP SEARCH INDEX 和 CREATE SEARCH INDEX 丢弃并重新创建搜索索引。如需了解每个子类型的步骤,请参阅未实现功能或操作。

503 - 服务不可用

原因 HTTP 状态代码 说明 问题排查
backendError 503

由于以下原因之一,服务暂时不可用:

  • 服务需求激增(减载)或内部资源耗尽。
  • 间歇性网络连接问题。
  • 暂时性后端组件问题。

错误返回:Error encountered during execution. Retrying may solve the problem.

使用截断指数退避算法重试请求,并使用新的 jobId 重试失败的作业。如果重试后错误仍然存在,请将 30 天失败率与 BigQuery SLA 进行比较,并与 Cloud Customer Care 联系;请参阅排查 backendError 错误。