Package google.rpc

索引

程式碼

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) 如果用戶端應在較高層級重試 (例如當用戶端指定的「test-and-set」失敗時，表示用戶端應重新開始「read-modify-write」序列)，請使用 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 內部伺服器錯誤

狀態

Status 類型會定義適用於不同程式設計環境 (包含 REST API 和遠端程序呼叫 (RPC) API) 的邏輯錯誤模型。gRPC 會使用這個模型。錯誤模型的設計目標如下：

  • 讓大部分使用者容易使用和理解
  • 足夠靈活彈性，可以滿足意外需求

總覽

Status 訊息包含三部分的資料：錯誤代碼、錯誤訊息和錯誤詳細資料。錯誤代碼應為 google.rpc.Code 的列舉值，但可以視需要接受其他錯誤代碼。錯誤訊息應以英文向開發人員顯示，協助開發人員瞭解及解決錯誤。如果需要向本地使用者顯示的錯誤訊息，請在錯誤詳細資料中加入本地化訊息，或在用戶端中將錯誤訊息本地化。選用的錯誤詳細資料可能包含有關錯誤的任意資訊。套件 google.rpc 中有一組預先定義的錯誤詳細資料類型，可用於常見的錯誤情況。

語言對應

Status 訊息是錯誤模型的邏輯表示法，但不一定是實際的線路格式。當 Status 訊息在不同用戶端程式庫和不同連線通訊協定中公開時，對應方式可能有所不同。例如，它可能會對應到 Java 中的某些例外狀況，但更有可能會對應到 C 中的某些錯誤代碼。

其他用法：

無論是否使用 API，錯誤模型和 Status 訊息都適用於各種環境，可為不同環境提供一致的開發人員體驗。

這個錯誤模型的使用範例包括：

  • 部分錯誤。如果服務需要向用戶端傳回部分錯誤，可以在正常回應中嵌入 Status，指出部分錯誤。

  • 工作流程錯誤。一般工作流程含有多個步驟。每個步驟都可能顯示 Status 訊息，方便您回報錯誤。

  • 批次作業。如果用戶端使用批次要求和批次回應，則應直接在批次回應中使用 Status 訊息，每個錯誤子回應各使用一則訊息。

  • 非同步作業。如果 API 呼叫會在回應中嵌入非同步作業結果，這些作業的狀態應直接以 Status 訊息表示。

  • 記錄。如果記錄檔中儲存了部分 API 錯誤，則可直接使用 Status 訊息，但須先基於安全性/隱私權考量進行任何必要的清除作業。

欄位
code

int32

狀態碼，應為 google.rpc.Code 的列舉值。
message

string

向開發人員顯示的錯誤訊息，應以英文呈現。所有向使用者顯示的錯誤訊息都應經過本地化，並透過 google.rpc.Status.details 欄位傳送，或是由用戶端加以本地化。
details[]

Any

包含錯誤詳細資料的訊息清單。API 可以使用一組常用的訊息類型。