Code

gRPC API 的標準錯誤代碼。

有時可能適用多個錯誤代碼。服務應傳回最適用的特定錯誤代碼。例如，如果 OUT_OF_RANGE 與 FAILED_PRECONDITION 代碼都適用，則最好使用前者。同樣地，偏好採用 NOT_FOUND 或 ALREADY_EXISTS，而非 FAILED_PRECONDITION。

列舉
OK

非錯誤；於成功時傳回。

HTTP 對應：200 OK
CANCELLED

作業已取消，一般由呼叫者取消。

HTTP 對應：499 用戶端已關閉要求
UNKNOWN

不明的錯誤。舉例來說，如果從其他位址空間收到的 Status 值屬於這個位址空間中不明的錯誤空間，系統可能會傳回這個錯誤。由 API 發出但未傳回充分錯誤資訊的錯誤，也可能會轉換為此錯誤。

HTTP 對應：500 內部伺服器錯誤
INVALID_ARGUMENT

用戶端指定了無效的引數。請注意，這與 FAILED_PRECONDITION 不同。INVALID_ARGUMENT 代表系統狀態的問題引數 (例如格式錯誤的檔案名稱)。

HTTP 對應：400 錯誤的要求
DEADLINE_EXCEEDED

期限於作業完成之前過期。針對變更系統狀態的作業，即使作業已成功完成，也可能傳回此錯誤。例如，來自伺服器的成功回應延遲時間可能已長到足以使期限過期。

HTTP 對應：504 閘道逾時
NOT_FOUND

找不到某些要求的實體 (例如檔案或目錄)。

伺服器開發人員注意事項：如果要求的所有使用者 (例如逐步推出功能或未記錄到的許可清單) 遭到拒絕，系統可能會使用 NOT_FOUND。如果針對部分使用者 (例如使用者存取權控管機制) 中的部分使用者拒絕要求，則必須使用 PERMISSION_DENIED。

HTTP 對應：404 找不到
ALREADY_EXISTS

用戶端嘗試建立的實體 (例如檔案或目錄) 已存在。

HTTP 對應：409 衝突
PERMISSION_DENIED

呼叫者沒有執行指定作業的權限。對於因耗用某些資源所導致的拒絕情形，不得使用 PERMISSION_DENIED (請針對這些錯誤改用 RESOURCE_EXHAUSTED)。如果無法識別呼叫者，不得使用 PERMISSION_DENIED (請針對這些錯誤改用 UNAUTHENTICATED)。此錯誤代碼並不表示要求有效，或是要求的實體已存在或是滿足其他先決條件。

HTTP 對應：403 禁止
UNAUTHENTICATED

要求沒有作業的有效驗證憑證。

HTTP 對應：401 未授權
RESOURCE_EXHAUSTED

已耗盡某些資源，或許是每位使用者的配額，或許是完整檔案系統空間不足。

HTTP 對應：429 太多要求
FAILED_PRECONDITION

作業已遭拒絕，因為系統不在執行作業所需的狀態下。例如要刪除的目錄非空白、rmdir 作業套用至非目錄等。

服務實作人員可根據下列規範，決定 FAILED_PRECONDITION、ABORTED 和 UNAVAILABLE 之間：(a) 如果用戶端只重試失敗的呼叫，請使用 UNAVAILABLE。(b) 如果用戶端應以較高層級重試，請使用 ABORTED。例如，當用戶端指定的測試和設定失敗時，代表用戶端應重新啟動讀取 - 修改 - 寫入序列。(c) 若用戶端未明確修正系統狀態，不應重試，請使用 FAILED_PRECONDITION。例如，如果目錄因為空白而失敗，因而傳回「rmdir」，則除非檔案從目錄中刪除，否則應傳回 FAILED_PRECONDITION。

HTTP 對應：400 錯誤的要求
ABORTED

作業已取消，原因通常是排序器檢查失敗或交易取消等並行問題。

如要決定採用 FAILED_PRECONDITION、ABORTED 還是 UNAVAILABLE，請參閱以上指南。

HTTP 對應：409 衝突
OUT_OF_RANGE

嘗試作業時超過有效範圍，例如搜尋或讀取超過檔案結尾。

與 INVALID_ARGUMENT 不同，此錯誤表示如果系統狀態變更則可修正的問題。例如，如果系統要求讀取不在指定範圍 [0,2^32-1] 內的偏移中的 32 位元檔案系統，則系統會產生 INVALID_ARGUMENT，但如果要求從超過目前檔案大小的偏移讀取，則會產生 OUT_OF_RANGE。

FAILED_PRECONDITION與OUT_OF_RANGE之間重疊部分。應用程式在適用情況下，建議使用 OUT_OF_RANGE (更具體的錯誤)，這樣透過空格疊代疊代的呼叫端，即可偵測 OUT_OF_RANGE 錯誤，以偵測是否完成時。

HTTP 對應：400 錯誤的要求
UNIMPLEMENTED

未實作作業或作業在此服務中不受支援/未啟用。

HTTP 對應：501 未實作
INTERNAL

內部錯誤。這表示基礎系統預期的某些不變的情形已被打破。此錯誤代碼保留供嚴重錯誤使用。

HTTP 對應：500 內部伺服器錯誤
UNAVAILABLE

服務目前無法使用。這極有可能是暫時情況，只要使用重試即可重試。請注意，重試非冪等作業並不安全。

如要決定採用 FAILED_PRECONDITION、ABORTED 還是 UNAVAILABLE，請參閱以上指南。

HTTP 對應：503 服務不可用
DATA_LOSS

無法復原的資料遺失或損毀。

HTTP 對應：500 內部伺服器錯誤