狀態回應代碼

下列狀態碼可在 gRPC 回應中傳回,適用於本網站記錄的所有 gRPC 版本。

代碼 狀態 附註
0 OK 退貨期限:Success
1 CANCELLED 作業已取消 (通常由呼叫端取消)。
2 UNKNOWN 舉例來說,如果從其他位址空間收到的「Status」值屬於這個位址空間中不明的錯誤空間,就可能傳回這個錯誤。由 API 發出但未傳回足夠錯誤資訊的錯誤也可能轉換為此錯誤。
3 INVALID_ARGUMENT 用戶端指定了無效的引數。
4 DEADLINE_EXCEEDED 期限在作業完成前已過期。針對會變更系統狀態的作業,即便作業順利完成也有可能會傳回這個錯誤。例如伺服器成功回應,但延遲時間過長而導致超過期限。
5 NOT_FOUND 找不到某些要求的實體。
6 ALREADY_EXISTS 用戶端嘗試建立的實體已存在。
7 PERMISSION_DENIED 呼叫者沒有執行指定作業的權限。請勿將 PERMISSION_DENIED 用於因耗用某些資源而導致的拒絕情形;請針對這些錯誤改用 RESOURCE_EXHAUSTED。無法識別呼叫端時,請勿使用 PERMISSION_DENIED (請針對這些錯誤改用 UNAUTHENTICATED)。接收 PERMISSION_DENIED 錯誤代碼並不表示要求有效,或是要求的實體已存在或滿足其他先決條件。
8 RESOURCE_EXHAUSTED 已耗盡某些資源 (可能是每位使用者的配額,也可能是整個檔案系統的空間不足)。
9 FAILED_PRECONDITION 作業已遭拒絕,因為系統未處於執行該作業所需的狀態,例如要刪除的目錄非空白,或 rmdir 作業套用至非目錄。
10 ABORTED 作業已取消,原因通常是排序器檢查失敗或交易取消等並行問題。
11 OUT_OF_RANGE 嘗試執行的作業超出有效範圍。
12 UNIMPLEMENTED 作業未在這項服務中實作,或不支援/未啟用。
13 INTERNAL 發生內部錯誤,這表示基礎系統預期的特定不變值已損毀。此錯誤代碼保留給嚴重錯誤使用。
14 UNAVAILABLE 目前無法提供服務;這極有可能是暫時狀況,只要使用輪詢重試即可修正。
15 DATA_LOSS 無法復原的資料遺失或損毀。
16 UNAUTHENTICATED 要求沒有該作業的有效驗證憑證。

有時可能有多個錯誤代碼適用,服務應傳回最適用的特定錯誤代碼。例如,如果兩個代碼都適用,則建議使用 OUT_OF_RANGE 而非 FAILED_PRECONDITION。同樣地,NOT_FOUNDALREADY_EXISTS 應優先於 FAILED_PRECONDITION

FAILED_PRECONDITION、ABORTED 與 UNAVAILABLE 的比較

以下為細項測試,可協助您決定 FAILED_PRECONDITIONABORTEDUNAVAILABLE

  • 如果用戶端只能重試失敗的呼叫,請使用 UNAVAILABLE
  • 如果用戶端應在較高層級重試 (例如用戶端指定的 test-and-set 失敗),因而表示用戶端應重新啟動「讀取 - 修改 - 寫入」序列,請使用 ABORTED
  • 如果用戶端不應在系統狀態明確修正完畢前重試,請使用 FAILED_PRECONDITION。舉例來說,如果「rmdir」因目錄不是空白而失敗,最好傳回 FAILED_PRECONDITION,因為除非已從目錄中刪除檔案,否則用戶端不應重試。

INVALID_ARGUMENT、FAILED_PRECONDITION 與 OUT_OF_RANGE 的比較

以下為細項測試,可協助您決定 INVALID_ARGUMENTFAILED_PRECONDITIONOUT_OF_RANGE

  • 如果引數有問題,無論系統狀態為何,請使用 INVALID_ARGUMENT。例如:網址格式錯誤
  • 如果值因系統狀態而超出範圍,請使用 OUT_OF_RANGE。例如,start_date 早於 start_date_restrict
  • 如果值因系統狀態而無效,但並非 OUT_OF_RANGE 值,請使用 FAILED_PRECONDITION