错误消息

本文档介绍使用 BigQuery 时可能会遇到的错误消息，包括 HTTP 错误代码、作业错误和 Google Cloud 控制台错误消息。作业错误会在调用 jobs.get 时通过 status 对象表示。

错误表

BigQuery API 的响应在响应正文中包含 HTTP 错误代码和错误对象。错误对象通常是以下各项之一：

• errors 对象，包含一个 ErrorProto 对象数组。
• 一个 errorResults 对象，其中包含一个 ErrorProto 对象。

下表中的错误消息列会映射到 ErrorProto 对象中的 reason 属性。

下表并未包含所有可能的 HTTP 错误或其他网络错误。因此，请勿假设 BigQuery 的每个错误响应中都存在错误对象。此外，如果您使用适用于 BigQuery API 的 Cloud 客户端库，您可能会收到不同的错误或错误对象。如需了解详情，请参阅 BigQuery API 客户端库。

如果收到的 HTTP 响应代码未显示在下表中，则该响应代码表示该 HTTP 请求存在问题或结果符合预期。5xx 范围内的响应代码表示服务器端错误。如果您收到 5xx 响应代码，则请稍后重试请求。在某些情况下，中间服务器（如代理）可能会返回 5xx 响应代码。检查响应正文和响应标头以详细了解错误。如需查看 HTTP 响应代码的完整列表，请参阅 HTTP 响应代码。

如果您使用 bq 命令行工具检查作业状态，则系统默认不会返回错误对象。如需查看映射到下表的错误对象以及相应的 reason 属性，请使用 --format=prettyjson 标志。例如：bq --format=prettyjson show -j <job id>

错误消息	HTTP 代码	说明	问题排查
accessDenied	403	当您尝试访问您无权访问的数据集、表、视图或作业等资源时，系统会返回此错误。当尝试修改只读对象时，也会返回此错误。	联系资源所有者，并为错误审核日志中的 principalEmail 值标识的用户请求获取该资源的访问权限。
backendError	500 或 503	当存在临时服务器故障（例如网络连接问题或服务器过载）时，系统会返回此错误。	通常，您需要等待几秒钟，然后再重试一次。不过，排查此错误时有两种特殊情况：jobs.get 调用和 jobs.insert 调用。 jobs.get 调用 如果您在轮询 jobs.get 时收到 503 错误，请等待几秒钟再重新轮询。 如果作业完成，但出现包含 backendError 的错误对象，则表示作业失败。您可以安全地重试该作业，而不用担心数据一致性。 jobs.insert 调用 如果您在进行 jobs.insert 调用时收到此错误，则无法确定作业是否成功。在此情况下，您需要重试该作业。
billingNotEnabled	403	当项目未启用结算时，会返回此错误。	请在 Google Cloud Console 中为项目启用结算功能。
billingTierLimitExceeded	400	当按需作业的值 statistics.query.billingTier 超过 100 时，系统会返回此错误。当按需查询使用的 CPU 数量相对于扫描的数据量过多时，会发生这种情况。如需了解如何检查作业统计信息，请参阅管理作业。	此错误最常见的原因是显式或隐式执行低效的交叉联接（例如联接条件不精确）。这些类型的查询因资源消耗量较大而不适合按需价格模式，且通常扩缩能力不佳。您可以优化查询，也可以改用固定价格来解决此错误。如需了解如何优化查询，请参阅避免 SQL 反模式。
blocked	403	当 BigQuery 暂时将您尝试执行的操作列入拒绝名单（通常是为了防止服务中断）时，会返回此错误。	如需了解详情，请与支持团队联系。
duplicate	409	当尝试创建的作业、数据集或表已存在时，系统会返回此错误。如果作业的 writeDisposition 属性设置为 WRITE_EMPTY，且作业访问的目标表已存在，也会返回此错误。	请重命名您尝试创建的资源，或更改作业的 writeDisposition 值。
internalError	500	当 BigQuery 发生内部错误时，系统会返回此错误。	根据 BigQuery 服务等级协议中的退避要求等待，然后重新尝试操作。如果错误仍然存在，请与支持团队联系，或使用 BigQuery 问题跟踪器报告错误。您还可以尝试使用预留来降低此错误的频率。
invalid	400	当存在无效查询之外的任何种类无效输入（例如，缺少必填字段或表架构无效）时，系统会返回此错误。无效查询返回 invalidQuery 错误。
invalidQuery	400	当尝试运行无效查询时，会返回此错误。	检查查询是否存在语法错误。查询参考中包含有关如何构造有效查询的说明和示例。
invalidUser	400	当您尝试安排具有无效用户凭据的查询时，系统会返回此错误。	按照安排查询中的说明刷新用户凭据。
jobBackendError	400	当作业创建成功但因内部错误而失败时，系统会返回此错误。您可能会在 jobs.query 或 jobs.getQueryResults 中看到此错误。	使用新的 jobId 重试作业。如果错误仍然存在，请与支持团队联系。
jobInternalError	400	当作业创建成功但因内部错误而失败时，系统会返回此错误。您可能会在 jobs.query 或 jobs.getQueryResults 中看到此错误。	使用新的 jobId 重试作业。如果错误仍然存在，请与支持团队联系。
notFound	404	当您引用的资源（数据集、表或作业）不存在或请求中的位置与资源的位置不匹配时（例如，运行作业的位置），系统会返回此错误。如果使用表修饰器引用最近执行过流式插入操作的表，但该表已被删除，也可能会发生此错误。	在查询已删除的表之前，请更正资源名称、正确指定位置或在流式插入后至少等待 6 个小时。
notImplemented	501	当尝试访问未实现的功能时，会返回此作业错误。	如需了解详情，请与支持团队联系。
quotaExceeded	403	如果您的项目超过 BigQuery 配额、自定义配额，或者如果您尚未设置结算功能并且已超过查询的免费层级，则系统会返回此错误。	请查看错误对象的 message 属性，详细了解超出了哪一项配额。要重置或提高 BigQuery 配额，请与支持团队联系。要修改自定义配额，请通过 Google Cloud 控制台页面提交申请。如果您在使用 BigQuery 沙盒时收到此错误，则可以从沙盒升级。 如需了解详情，请参阅排查 BigQuery 配额错误。
rateLimitExceeded	403	如果您的项目在很短时间内发送的请求过多，导致超出短期速率限制，则系统会返回此错误。例如，请参阅查询作业的速率限制和 API 请求的速率限制。	请降低请求速率。 如果您确信项目未超过其中任何一项限制，请与支持团队联系。 如需了解详情，请参阅排查 BigQuery 配额错误。
resourceInUse	400	当尝试删除包含表的数据集或当前正在运行的作业时，会返回此错误。	在清空数据集后再尝试删除该数据集，或者等待作业完成后再删除该作业。
resourcesExceeded	400	查询使用太多资源时，会返回此错误。	请尝试将查询分解为多个较小的查询。 请尝试移除 ORDER BY 子句。 如果您的查询使用 JOIN，请确保较大的表位于子句左侧。 如果您的查询使用 FLATTEN，请确定它对于您的用例来说是否必要。 如需了解详情，请参阅嵌套重复的数据。 如果您的查询使用 EXACT_COUNT_DISTINCT，建议改用 COUNT(DISTINCT)。 如果您的查询使用 COUNT(DISTINCT <value>, <n>) 和较大的 <n> 值，建议改用 GROUP BY。如需了解详情，请参阅 COUNT(DISTINCT)。 如果您的查询使用 UNIQUE，建议改用 GROUP BY，或子选择内的窗口函数。 如果查询使用 LIMIT 子句具体化许多行，请考虑对其他列（例如 ROW_NUMBER()）进行过滤，或完全移除 LIMIT 子句以允许并行处理写入操作。
responseTooLarge	403	当查询结果大于最大响应大小时，会返回此错误。某些查询会分多个阶段执行。当任何阶段返回的响应大小过大时，系统便会返回此错误，即使最终结果未超过大小上限也是如此。如果查询使用 ORDER BY 子句，系统通常会返回此错误。	请添加 LIMIT 子句（有时会有所帮助），或移除 ORDER BY 子句。如要确保大型结果能够顺利返回，您可以将 allowLargeResults 属性设置为 true 并指定目标表。如需了解详情，请参阅 写入大型查询结果。
已停止	200	当取消作业时，会返回此状态代码。
tableUnavailable	400	某些 BigQuery 表由其他 Google 产品团队管理的数据提供支持。此错误表示其中一个表不可用。	收到此错误消息时，您可以重试请求（请参阅 internalError 问题排查建议），或联系授予您数据访问权限的 Google 产品团队。
timeout	400	作业超时。	请考虑减少操作执行的工作量，以便能够在设定的限制内完成。请参阅配额和限制。

错误响应示例

GET https://bigquery.googleapis.com/bigquery/v2/projects/12345/datasets/foo
Response:
[404]
{
  "error": {
  "errors": [
  {
    "domain": "global",
    "reason": "notFound",
    "message": "Not Found: Dataset myproject:foo"
  }],
  "code": 404,
  "message": "Not Found: Dataset myproject:foo"
  }
}

身份验证错误

如 OAuth2 规范所定义，OAuth 令牌生成系统引发的错误会返回以下 JSON 对象。

{"error" : "description_string"}

此错误会伴随着 HTTP 400 Bad Request 错误或 HTTP 401 Unauthorized 错误。description_string 是由 OAuth2 规范定义的其中一个错误代码。例如：

{"error":"invalid_client"}

返回页首

排查流式插入问题

以下部分讨论如何排查在将数据流式插入到 BigQuery 时发生的错误。 如需详细了解如何解决流式插入的配额错误，请参阅流式插入配额错误。

失败 HTTP 响应代码

如果收到失败的 HTTP 响应代码（如网络错误），则无法确定流式插入是否成功。如果只是尝试重新发送请求，则可能导致最终表中出现重复的行。为了避免表中出现重复的内容，请在发送请求时设置 insertId 属性。BigQuery 会使用 insertId 属性执行去重操作。

如果您收到权限错误、表名称无效错误或超出配额错误，则系统不会插入任何行，并且整个请求都会失败。

成功 HTTP 响应代码

即使您收到成功 HTTP 响应代码，也需要检查响应的 insertErrors 属性才能确定是否成功插入行，因为 BigQuery 可能只是成功插入了部分行。 您可能会遇到以下情况之一：

• 已成功插入所有行。如果 insertErrors 属性是空列表，则表示所有行均已成功插入。
• 已成功插入一些行。insertErrors 属性中指示的行并未插入，而其他所有行则已成功插入（除非任何行中存在架构不匹配的情况）。errors 属性详细说明了每个未成功插入行的失败原因。index 属性指示请求中与错误对应的行索引（从 0 开始）。
• 未成功插入任何行。如果 BigQuery 在请求的个别行上遇到架构不匹配的情况，则系统不会插入任何行，并会针对每一行（即使是架构匹配的行）返回一个 insertErrors 条目。对于架构匹配的行，其所对应错误的 reason 属性将设置为 stopped，因此您可以按原样重新发送这些行。而对于插入失败的行，其会包含有关架构不匹配情况的详细信息。如需了解每种 BigQuery 数据类型支持的协议缓冲区类型，请参阅数据类型转换。

流式插入的元数据错误

由于 BigQuery 的流式插入 API 可以实现高插入速率，因此在与流式插入系统进行交互时，对底层表元数据展示的修改最终将保持一致。大多数时候，元数据更改会在几分钟内完成传送，但在此期间，API 响应可能会反映表的不一致状态。

部分情况包括：

• 架构更改。针对最近接收了流式插入内容的表修改架构时，响应可能会指出架构不匹配错误，因为流式插入系统可能不会立即反映架构更改。
• 表创建/删除。如果将数据流式插入到不存在的表，则系统将返回 notFound 响应的变体。后续流式插入作业可能无法立即识别在响应中创建的表。同样地，删除或重新创建表可能造成在一段时间内流式插入实际上传输到旧表。流式插入可能不会出现在新表中。
• 表截断。截断表的数据（通过使用 WRITE_TRUNCATE 的 writeDisposition 的查询作业）同样可能导致在一致性期间的后续插入丢失。

数据丢失/不可用

流式插入临时驻留在写入优化存储空间中，该存储空间具有不同于代管式存储空间的可用性特征。BigQuery 中的某些操作不与写入优化存储空间交互，例如表复制作业和 tabledata.list 等 API 方法。最近流式插入的数据将不会出现在目标表或输出中。

返回页首

Google Cloud 控制台错误消息

下表列出了使用 Google Cloud 控制台时可能会看到的错误消息。

错误消息	说明	问题排查
服务器返回未知错误响应。	当 Google Cloud 控制台从服务器收到未知错误时，会显示此错误；例如，当您点击数据集或其他类型的链接时，页面无法显示。	请尝试切换到浏览器的无痕模式或不公开模式，然后重复导致该错误的操作。如果无痕模式下没有出现错误，则错误可能是由浏览器扩展程序（例如广告拦截器）导致的。尝试在非无痕模式下停用浏览器扩展程序，看看是否能解决问题。

返回页首