本頁面說明 BigQuery API 傳回的 HTTP 狀態碼和錯誤訊息。您可以參考這些代碼來疑難排解及解決要求失敗的問題,並驗證 API 行為。
如要進一步瞭解非 API 錯誤、用戶端程式庫連線能力錯誤和 Google Cloud 控制台錯誤,請參閱「錯誤訊息」。
如要進一步瞭解查詢錯誤,請參閱「排解查詢錯誤」。
如要進一步瞭解串流資料即時插入錯誤,請參閱「排解串流資料即時插入問題」。
錯誤回應格式
BigQuery 的 API 採用標準 HTTP 錯誤報告格式。成功的要求會傳回 2xx 範圍內的 HTTP 狀態碼。失敗的要求會傳回 4xx 和 5xx 範圍內的狀態碼。需要重新導向的要求會傳回 3xx 範圍內的狀態碼。錯誤回應通常會在回應主體中包含 JSON 文件,其中含有錯誤物件,內含錯誤相關資訊。
在 BigQuery API 回應中,錯誤物件通常是下列其中一項:
errors物件:包含ErrorProto物件陣列。errorResults物件,其中包含單一ErrorProto物件。
本頁狀態碼表格中的「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 陳述式嘗試修改最近透過舊版 |
請改用 BigQuery Storage Write API (gRPC),等待幾分鐘讓串流緩衝區清除,或篩選陳述式來排除最近串流的資料列。詳情請參閱「在含有串流緩衝區的資料表上執行 DML 陳述式」。 |
invalid |
400 |
要求包含無效的輸入內容 (不含無效查詢),包括下列情況:
|
請確保提供的結構定義與現有資料欄和模式相符,將超過 15 層巢狀結構的結構扁平化 (或儲存為 |
invalidQuery |
400 |
SQL 查詢未通過驗證或執行檢查,原因如下:
|
請檢查 |
jobBackendError |
400 |
在 |
使用截斷指數輪詢,以新的 |
jobInternalError |
400 |
在 |
使用截斷指數輪詢,以新的 |
preconditionFailed |
400 |
不符合要求的前提條件,包括下列情況:
|
請先擷取目前的資源 |
resourceInUse |
400 |
刪除要求指定的資源仍在使用中或已填入資料:
傳回的錯誤訊息: |
請先清空資料集再刪除 (或設定 |
resourcesExceeded |
400 |
工作在下列任一方面的執行資源用量超出限制:
傳回的錯誤訊息: |
簡化查詢、批次處理 DML 作業、減少掃描的資料欄或分區、避免在同一個工作階段中執行並行工作,或為重度重組的工作負載佈建專屬運算單元容量。如需各子類型的步驟,請參閱「排解資源超出限制的問題」和「查詢超出記憶體資源」。 |
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,移除非預期的笛卡兒乘積、不精確的 join、未分區的視窗函式或繁重的 JavaScript UDF,或改用依運算能力 (運算單元) 計費。詳情請參閱「查詢超出 CPU 資源」和「避免反 SQL 模式」。 |
bytesBilledLimitExceeded |
400 |
查詢在執行前預估的位元組上限超過 |
請模擬測試來預覽預估位元組數、只選取所需資料欄,並篩選分區資料欄,以減少資料處理量,或將 |
jobRateLimitExceeded |
400 |
在
|
減少同時提交的作業 (或使用批次優先順序或運算單元自動調度資源功能,進行持續查詢),然後使用截斷指數輪詢,以新的 |
timeout |
400 |
作業超過執行時間限制,包括下列情況:
|
篩選分區或分群資料欄,並將複雜或多陳述式查詢拆分為較小的階段,或在建立外部資料表時指定明確的結構定義和較窄的來源 URI。詳情請參閱「查詢超過執行時間限制」和「排解配額和限制錯誤」。 |
invalidUser |
400 |
排定的查詢設定了無效的使用者憑證。 |
重新整理排定查詢的使用者憑證。詳情請參閱「排定查詢」。 |
required |
400 |
執行前缺少必要輸入內容:
傳回的錯誤訊息: |
請在 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 或應用程式預設憑證,在以服務帳戶身分執行或模擬服務帳戶時,授予 |
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 |
查詢或資料表讀取回應超過大小限制,原因如下:
傳回的錯誤訊息: |
請指定目的地資料表 (並將 |
apiLimitExceeded |
403 |
要求超出下列其中一項 API 或中繼資料限制:
傳回的錯誤訊息: |
使用截斷指數輪詢重試失敗的要求、批次載入和讀取、簡化精細的個別資料表 IAM 或資料列層級安全性政策,並等待滾動週期結束後再新增資料集副本。詳情請參閱「API 頻率和中繼資料評估限制錯誤」和「跨區域資料集副本建立限制錯誤」。 |
quotaExceeded |
403 |
您的專案超過下列其中一項用量配額:
傳回的錯誤訊息: |
檢查錯誤 |
rateLimitExceeded |
403 |
要求因下列其中一項頻率或並行限制而遭拒:
|
請降低要求比率,並使用截斷指數輪詢重試,或以批次優先順序執行非緊急查詢,並調整預留項目並行或運算單元自動調度資源。詳情請參閱「排解配額和限制錯誤」和「查詢許可遭拒」。 |
accessDenied |
403 |
基於下列其中一項原因,系統拒絕存取 BigQuery 資源:
傳回的錯誤訊息: |
檢查 Cloud 稽核記錄 ( |
policyViolation |
403 |
安全範圍或組織政策封鎖了要求:
|
請依 |
billingNotEnabled |
403 |
專案未啟用計費功能,無法執行要求的作業:
傳回的錯誤訊息: |
在Google Cloud 控制台中啟用專案計費功能,從 BigQuery 沙箱升級,然後更新資料表、檢視表和分區的預設到期時間。詳情請參閱「專案未啟用計費功能」。 |
blocked |
403 |
BigQuery 暫時將嘗試執行的作業加入拒絕清單,以免服務中斷。傳回的錯誤: |
與 Cloud Customer Care 團隊聯絡,並提供確切的時間戳記、專案 ID 和 BigQuery 工作 ID,以便調查管理緩解規則。詳情請參閱「為保護系統運作,要求已遭封鎖」。 |
termsOfServiceNotAccepted |
403 |
專案尚未接受《BigQuery 服務條款》。錯誤會傳回: |
登入 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 |
找不到要求的資源,可能原因如下:
傳回的錯誤訊息: |
請確認專案、資料集和資料表 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 |
作業因並行修改或衝突而停止 (傳回的原因拼寫為 |
|
duplicate |
409 |
要求與現有資源發生衝突,可能原因如下:
傳回的錯誤訊息: |
請使用其他資源名稱、在 DDL 陳述式中使用 |
499 - 用戶端已關閉要求
| 原因 | HTTP 狀態碼 | 說明 | 疑難排解 |
|---|---|---|---|
stopped |
499 |
工作在完成前停止,原因可能是下列其中一項 (輪詢
傳回的錯誤訊息: |
請提高 |
500 - 內部伺服器錯誤
| 原因 | HTTP 狀態碼 | 說明 | 疑難排解 |
|---|---|---|---|
internalError |
500 |
BigQuery 發生內部錯誤。錯誤傳回:
|
請按照《BigQuery 服務水準協議》中的輪詢規定等待,並使用截斷指數輪詢重試,或使用預留項目降低暫時性錯誤頻率。詳情請參閱「排解 internalError 錯誤」。 |
501 — Not implemented
| 原因 | HTTP 狀態碼 | 說明 | 疑難排解 |
|---|---|---|---|
notImplemented |
501 |
要求嘗試對目標資源使用未實作的功能或作業,例如:
傳回的錯誤訊息: |
使用 |
503 — 無法使用服務
| 原因 | HTTP 狀態碼 | 說明 | 疑難排解 |
|---|---|---|---|
backendError |
503 |
服務暫時無法使用,可能原因如下:
傳回的錯誤: |
使用截斷指數輪詢重試要求,並使用新的 |