Package google.rpc

索引

BadRequest

說明用戶端要求中的違規事項。這類錯誤著重於要求的語法層面。

欄位
field_violations[]

FieldViolation

說明用戶端要求中的所有違規事項。

FieldViolation

用於說明單一錯誤要求欄位的訊息類型。

欄位
field

string

路徑會導向要求主體中的欄位。這個值會是以半形句號分隔的 ID 序列，用於識別通訊協定緩衝區欄位。

請考量下列事項：

message CreateContactRequest {
  message EmailAddress {
    enum Type {
      TYPE_UNSPECIFIED = 0;
      HOME = 1;
      WORK = 2;
    }

    optional string email = 1;
    repeated EmailType type = 2;
  }

  string full_name = 1;
  repeated EmailAddress email_addresses = 2;
}

在這個範例中，proto field 可以採用下列其中一個值：

  • full_name 違反 full_name 值
  • email_addresses[1].email，因為第一則email_addresses訊息的email欄位有違規情形
  • email_addresses[3].type[2]，因為第三則 email_addresses 訊息中的第二個 type 值有違規情形。

在 JSON 中，相同的值會表示為：

  • fullName 違反 fullName 值
  • emailAddresses[1].email，因為第一則emailAddresses訊息的email欄位有違規情形
  • emailAddresses[3].type[2]，因為第三則 emailAddresses 訊息中的第二個 type 值有違規情形。
description

string

說明要求元素為何不佳。
reason

string

欄位層級錯誤的原因。這是常數值，用於識別欄位層級錯誤的近因。在 google.rpc.ErrorInfo.domain 的範圍內，這項值應可唯一識別 FieldViolation 的類型。長度不得超過 63 個字元，且必須符合 [A-Z][A-Z0-9_]+[A-Z0-9] 規則運算式，代表 UPPER_SNAKE_CASE。
localized_message

LocalizedMessage

針對欄位層級錯誤提供本地化錯誤訊息，可安全地傳回給 API 消費者。

程式碼

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。舉例來說，當用戶端指定的「test-and-set」失敗時，表示用戶端應重新開始「read-modify-write」序列。(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 內部伺服器錯誤

LocalizedMessage

提供可安全傳回給使用者的本地化錯誤訊息，並附加至 RPC 錯誤。

欄位
locale

string

使用的語言代碼遵循 https://www.rfc-editor.org/rfc/bcp/bcp47.txt 中定義的規格。例如：「en-US」、「fr-CH」、「es-MX」
message

string

上述語言代碼的本地化錯誤訊息。

狀態

Status 類型會定義適用於不同程式設計環境 (包含 REST API 和遠端程序呼叫 (RPC) API) 的邏輯錯誤模型。gRPC 會使用這個模型。每個 Status 訊息包含三部分的資料：錯誤代碼、錯誤訊息和錯誤詳細資料。

如要進一步瞭解這個錯誤模型，以及如何使用這個錯誤模型，請參閱 API 設計指南。

欄位
code

int32

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

string

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

Any

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