BigQuery API 的 HTTP 状态和错误代码

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

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

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

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

错误响应格式

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.google.com/billing. details。

在 Google Cloud 控制台中为项目启用结算功能,以从 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。

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