BigQuery API 的 HTTP 狀態和錯誤代碼

本頁面說明 BigQuery API 傳回的 HTTP 狀態碼和錯誤訊息。您可以參考這些代碼來疑難排解及解決要求失敗的問題,並驗證 API 行為。

如要進一步瞭解非 API 錯誤、用戶端程式庫連線能力錯誤和 Google Cloud 控制台錯誤,請參閱「錯誤訊息」。

如要進一步瞭解查詢錯誤,請參閱「排解查詢錯誤」。

如要進一步瞭解串流資料即時插入錯誤,請參閱「排解串流資料即時插入問題」。

錯誤回應格式

BigQuery 的 API 採用標準 HTTP 錯誤報告格式。成功的要求會傳回 2xx 範圍內的 HTTP 狀態碼。失敗的要求會傳回 4xx 和 5xx 範圍內的狀態碼。需要重新導向的要求會傳回 3xx 範圍內的狀態碼。錯誤回應通常會在回應主體中包含 JSON 文件,其中含有錯誤物件,內含錯誤相關資訊。

在 BigQuery API 回應中,錯誤物件通常是下列其中一項:

本頁狀態碼表格中的「Reason」(原因) 欄會對應至 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 錯誤原因的專屬 ID。

範例值包括 invalid、accessDenied 和 notFound。
message 錯誤說明。與錯誤相同。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 語法、ID 或資料類型無效。
  • 不符合功能選項或必要的分區篩選器。
  • 超過檢視表巢狀結構或分區輸出限制。
  • 並行 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 加密金鑰。
  • Standard 版本不支援的功能。
  • 寫入 Enterprise Plus 主要預留項目以外的容錯移轉資料集。
  • 對 CDC 基礎資料表執行 materialized view 查詢,且有待處理的 upsert。

請先擷取目前的資源 etag,再重試、指定必要的 Cloud Key Management Service 金鑰、在 Enterprise 或 Enterprise 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 並行佇列或工作階段並行限制。
  • Worker、UDF、重組或機器學習模型記憶體預算。
  • 資料表分區 (10,000 個分區) 或輸出資料欄限制。
  • Cloud Key Management Service CMEK 要求比率、串流讀取或跨區域資料移轉。
  • 查詢計畫複雜度限制。

傳回的錯誤訊息:Resources exceeded during query execution: details。

簡化查詢、批次處理 DML 作業、減少掃描的資料欄或分區、避免在同一個工作階段中執行並行工作,或為重度重組的工作負載佈建專屬運算單元容量。如需各子類型的步驟,請參閱「排解資源超出限制的問題」和「查詢超出記憶體資源」。

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,移除非預期的笛卡兒乘積、不精確的 join、未分區的視窗函式或繁重的 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 — Unauthorized

如果要求缺少有效的驗證憑證,您會收到類似下列的錯誤回應。

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 — 禁止存取

如果您沒有存取所要求資源的權限,就會收到類似以下的錯誤回應。

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 稽核記錄 (protoPayload.authorizationInfo) 和政策分析工具,找出缺少的權限,並授予最小權限預先定義 BigQuery 角色。詳情請參閱「排解常見的『存取遭拒』問題」。

policyViolation 403

安全範圍或組織政策封鎖了要求:

  • VPC Service Controls perimeter 會限制存取權 (包括 Google 雲端硬碟匯出作業或 VPC-SC 專案中的外部資料表)。
  • constraints/gcp.resourceLocations 等組織政策限制不允許這項作業。

請依 vpcServiceControlsUniqueIdentifier 篩選 Logs Explorer,並查看違規分析工具、使用 perimeter 內的 Cloud Storage bucket 匯出或載入資料,或選取組織政策限制允許的區域。詳情請參閱「排解違反政策錯誤」。

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 控制台,在歡迎頁面選取國家/地區和《服務條款》核取方塊 (如出現提示),然後按一下「Agree and continue」(同意並繼續)。詳情請參閱「未接受 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。

請確認專案、資料集和資料表 ID 及位置 (區分大小寫),在時間旅行期間內還原已刪除的資料表,重新執行快取結果資料表已過期的查詢,或確認外部 Cloud Storage 或 Google 雲端硬碟檔案是否存在。詳情請參閱「找不到資料表」、「找不到位置」和「找不到工作」。

409 — 衝突

如果您嘗試建立已存在的資源,會收到類似下方的錯誤回應。

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 稽核記錄中的 jobservice.cancel 呼叫。如需各子類型的步驟,請參閱「工作執行作業已取消」。

500 - 內部伺服器錯誤

原因 HTTP 狀態碼 說明 疑難排解
internalError 500

BigQuery 發生內部錯誤。錯誤傳回: An internal error occurred and the request could not be completed.

請按照《BigQuery 服務水準協議》中的輪詢規定等待,並使用截斷指數輪詢重試,或使用預留項目降低暫時性錯誤頻率。詳情請參閱「排解 internalError 錯誤」。

501 — Not implemented

原因 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 服務水準協議,並與 Cloud Customer Care 聯絡。詳情請參閱「排解 backendError 錯誤」。