本页面介绍了 BigQuery API 返回的 HTTP 状态代码和出错提示。您可以使用这些代码来排查和解决请求失败问题,并验证 API 行为。
如需详细了解非 API 错误、客户端库连接错误和 Google Cloud 控制台错误,请参阅错误消息。
如需详细了解查询错误,请参阅排查查询错误。
如需详细了解流式插入错误,请参阅排查流式插入问题。
错误响应格式
BigQuery 为其 API 使用标准 HTTP 错误报告格式。成功的请求会返回 2xx 范围内的 HTTP 状态代码。失败的请求会返回 4xx 和 5xx 范围内的状态代码。需要重定向的请求会返回 3xx 范围内的状态代码。错误响应通常在响应正文中包含一个 JSON 文档,其中包含一个错误对象,该对象包含有关错误的信息。
在 BigQuery API 响应中,错误对象通常是以下各项之一:
errors对象,包含一个ErrorProto对象数组。- 一个
errorResults对象,其中包含一个ErrorProto对象。
本页状态代码表中的原因列会映射到 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 语句尝试修改最近使用旧版 |
迁移到 BigQuery Storage Write API (gRPC),等待几分钟让流式传输缓冲区刷新,或过滤语句以排除最近流式传输的行。如需了解详情,请参阅对具有流式传输缓冲区的表执行 DML 语句。 |
invalid |
400 |
请求包含无效查询之外的无效输入,包括以下情况:
|
确保提供的架构与现有列和模式匹配,展平嵌套层级超过 15 层的结构(或将其存储为 |
invalidQuery |
400 |
SQL 查询因以下原因之一而无法通过验证或执行检查:
|
检查 |
jobBackendError |
400 |
在 |
使用截断指数退避算法,通过新的 |
jobInternalError |
400 |
在 |
使用截断指数退避算法,通过新的 |
preconditionFailed |
400 |
未满足请求前提条件,包括以下情况:
|
在重试之前,请提取当前资源 |
resourceInUse |
400 |
删除请求的目标资源仍处于活跃状态或已填充:
错误返回: |
在删除数据集之前清空数据集(或设置 |
resourcesExceeded |
400 |
作业在以下任一领域超出了执行资源限制:
错误返回: |
简化查询、批量执行 DML 操作、减少扫描的列或分区、避免在同一会话中运行并发作业,或为 Shuffle 密集型工作负载预配专用槽容量。如需了解每个子类型的步骤,请参阅排查资源超出限制的问题和查询超出内存资源。 |
storageUnusable |
400 |
由于服务侧存储问题,保存表数据的内部 BigQuery 存储空间暂时不可用。错误返回:
|
|
streamingDataUnavailable |
400 |
写入优化存储空间中最近流式传输的数据暂时无法供读取作业使用。错误返回: |
使用截断指数退避算法,通过新的 |
tableUnavailable |
400 |
BigQuery 无法读取其不管理数据的表,包括以下情况:
|
使用截断指数退避算法重试架构提取或后备表超时,或者验证 |
userOwnedResourceError |
400 |
当 BigQuery 访问您拥有的外部资源时,该资源会返回错误。系统会返回以下错误: |
检查错误消息中的 resource_type 和 resource_name,以确定外部资源,并解决 external_error 中报告的底层错误。如需了解详情,请参阅用户拥有的外部资源错误。 |
vortexDataUnavailable |
400 |
最近使用 BigQuery Storage Write API (gRPC) 流式传输到写入优化存储空间的数据暂时无法用于查询。错误返回: |
使用截断指数退避算法,通过新的 |
billingTierLimitExceeded |
400 |
按需查询超出了每个扫描数据限制的最大 CPU 使用量。错误返回: |
重构 SQL 以移除意外的笛卡尔积、不精确的联接、未分区的窗口函数或繁重的 JavaScript UDF,或者切换到基于容量(槽)的价格。如需了解详情,请参阅查询超出 CPU 资源和避免 SQL 反模式。 |
bytesBilledLimitExceeded |
400 |
在执行开始之前,查询的执行前上限字节数估算值超过了 |
通过试运行预览估算的字节数,仅选择所需的列,并对分区列进行过滤,以减少处理的数据量,或将 |
jobRateLimitExceeded |
400 |
在
|
减少并发提交(或对持续查询使用批量优先级或槽自动扩缩),然后使用截断指数退避算法,通过新的 |
timeout |
400 |
操作超出其执行时间限制,包括以下情况:
|
对分区列或聚簇列进行过滤,并将复杂查询或多语句查询拆分为较小的阶段,或者在创建外部表时指定显式架构和更窄的源 URI。如需了解详情,请参阅查询超出执行时间限制和排查配额和限制错误。 |
invalidUser |
400 |
计划查询配置了无效的用户凭据。 |
刷新计划查询的用户凭证。如需了解详情,请参阅安排查询。 |
required |
400 |
执行前缺少必需的输入:
错误返回: |
在 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 或应用默认凭据,在以服务账号身份运行或模拟服务账号时授予 |
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 |
查询或表读取响应通过以下方式之一超出大小限制:
错误返回: |
指定目标表(并将 |
apiLimitExceeded |
403 |
请求超出了以下 API 或元数据限制之一:
错误返回: |
使用截断指数退避算法重试失败的请求,批量加载和读取,简化精细的每表 IAM 或行级安全政策,并在添加数据集副本之前等待滚动窗口。如需了解详情,请参阅 API 速率和元数据评估限制错误以及跨区域数据集副本创建限制错误。 |
quotaExceeded |
403 |
您的项目超出了以下用量配额之一:
系统会返回以下错误: |
检查错误 |
rateLimitExceeded |
403 |
请求因以下速率或并发限制之一而被拒绝:
|
降低请求速率,并使用截断指数退避算法重试,或以批量优先级运行非紧急查询,并调整预留并发或槽自动扩缩。如需了解详情,请参阅排查配额和限制错误以及查询准入被拒。 |
accessDenied |
403 |
由于以下原因之一,对 BigQuery 资源的访问被拒:
错误返回: |
检查 Cloud Audit Logs ( |
policyViolation |
403 |
安全边界或组织政策阻止了请求:
|
按 |
billingNotEnabled |
403 |
项目缺少所请求操作的有效结算信息:
错误返回: |
在 Google Cloud 控制台中为项目启用结算功能,以从 BigQuery 沙盒升级,然后更新表、视图和分区的默认有效期。如需了解详情,请参阅未为项目启用结算功能。 |
blocked |
403 |
BigQuery 暂时将尝试的操作添加到拒绝清单中,以防止服务中断。错误返回: |
联系 Cloud Customer Care,并提供确切的时间戳、项目 ID 和 BigQuery 作业 ID,以便调查管理缓解规则。如需了解详情,请参阅请求被屏蔽,以保护系统运行。 |
termsOfServiceNotAccepted |
403 |
项目尚未接受《BigQuery 服务条款》。错误返回: |
登录 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 云端硬盘文件是否存在。如需了解详情,请参阅未找到表、未找到位置和未找到作业。 |
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 |
操作因并发修改或冲突而停止(返回的原因拼写为 |
|
duplicate |
409 |
请求会通过以下方式之一与现有资源发生冲突:
错误返回: |
请使用其他资源名称,在 DDL 语句中使用 |
499 - 客户端关闭了请求
| 原因 | HTTP 状态代码 | 说明 | 问题排查 |
|---|---|---|---|
stopped |
499 |
作业在完成之前停止,原因如下(轮询
错误返回: |
增加 |
500 - 内部服务器错误
| 原因 | HTTP 状态代码 | 说明 | 问题排查 |
|---|---|---|---|
internalError |
500 |
BigQuery 内部发生错误。错误返回:
|
根据 BigQuery 服务等级协议中的退避要求等待,然后使用截断指数退避算法重试,或使用预留来降低暂时性错误的频率。如需了解详情,请参阅排查 internalError 错误。 |
501 - 未实现
| 原因 | HTTP 状态代码 | 说明 | 问题排查 |
|---|---|---|---|
notImplemented |
501 |
请求尝试对目标资源使用未实现的功能或操作,例如:
错误返回: |
使用 |
503 - 服务不可用
| 原因 | HTTP 状态代码 | 说明 | 问题排查 |
|---|---|---|---|
backendError |
503 |
由于以下原因之一,服务暂时不可用:
错误返回: |
使用截断指数退避算法重试请求,并使用新的 |