本頁面由 Cloud Translation API 翻譯而成。

Package google.rpc

索引

BadRequest (訊息)
BadRequest.FieldViolation (訊息)
Code (列舉)
ErrorInfo (訊息)
Help (訊息)
Help.Link (訊息)
LocalizedMessage (訊息)
PreconditionFailure (訊息)
PreconditionFailure.Violation (訊息)
QuotaFailure (訊息)
QuotaFailure.Violation (訊息)
RequestInfo (訊息)
ResourceInfo (訊息)
RetryInfo (訊息)
Status (訊息)

BadRequest

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

欄位

欄位
`field_violations[]`	`FieldViolation` 說明用戶端要求中的所有違規事項。

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 內部伺服器錯誤

ErrorInfo

詳細說明錯誤原因。

如果「pubsub.googleapis.com」API 未啟用，則在與該 API 聯絡時會發生錯誤，例如：

{ "reason": "API_DISABLED"
  "domain": "googleapis.com"
  "metadata": {
    "resource": "projects/123",
    "service": "pubsub.googleapis.com"
  }
}

這項回應表示 pubsub.googleapis.com API 未啟用。

嘗試在缺貨區域建立 Spanner 執行個體時，系統會傳回以下錯誤：

{ "reason": "STOCKOUT"
  "domain": "spanner.googleapis.com",
  "metadata": {
    "availableRegions": "us-central1,us-east2"
  }
}

欄位

欄位
`reason`	`string` 錯誤原因。這是常數值，用於識別錯誤的近似原因。錯誤原因在特定錯誤網域中是獨一無二的。長度不得超過 63 個字元，且必須符合 `[A-Z][A-Z0-9_]+[A-Z0-9]` 規則運算式，代表 UPPER_SNAKE_CASE。
`domain`	`string` 「原因」所屬的邏輯分組。錯誤網域通常是產生錯誤的工具或產品的註冊服務名稱。例如「pubsub.googleapis.com」。如果錯誤是由某些常見基礎架構產生，錯誤網域必須是可識別基礎架構的全球專屬值。如果是 Google API 基礎架構，錯誤網域為「googleapis.com」。
`metadata`	`map<string, string>` 這項錯誤的額外結構化詳細資料。鍵必須符合 `[a-z][a-zA-Z0-9-_]+` 的規則運算式，但最好是 lowerCamelCase。長度不得超過 64 個半形字元。如要找出超出限制的目前值，單位應包含在鍵中，而非值中。舉例來說，如果用戶端超出單一 (批次) 要求可建立的執行個體數量，則應傳回 `{"instanceLimitPerRequest": "100"}`，而非 `{"instanceLimit": "100/request"}`。

reason

string

錯誤原因。這是常數值，用於識別錯誤的近似原因。錯誤原因在特定錯誤網域中是獨一無二的。長度不得超過 63 個字元，且必須符合 [A-Z][A-Z0-9_]+[A-Z0-9] 規則運算式，代表 UPPER_SNAKE_CASE。

domain

string

「原因」所屬的邏輯分組。錯誤網域通常是產生錯誤的工具或產品的註冊服務名稱。例如「pubsub.googleapis.com」。如果錯誤是由某些常見基礎架構產生，錯誤網域必須是可識別基礎架構的全球專屬值。如果是 Google API 基礎架構，錯誤網域為「googleapis.com」。

metadata

map<string, string>

這項錯誤的額外結構化詳細資料。

鍵必須符合 [a-z][a-zA-Z0-9-_]+ 的規則運算式，但最好是 lowerCamelCase。長度不得超過 64 個半形字元。如要找出超出限制的目前值，單位應包含在鍵中，而非值中。舉例來說，如果用戶端超出單一 (批次) 要求可建立的執行個體數量，則應傳回 {"instanceLimitPerRequest": "100"}，而非 {"instanceLimit": "100/request"}。

說明

提供說明文件連結，或執行頻外動作。

舉例來說，如果配額檢查失敗，且錯誤訊息指出呼叫專案尚未啟用存取的服務，這時錯誤訊息可能包含網址，直接指向開發人員控制台中的正確位置，方便您切換位元。

欄位

欄位
`links[]`	`Link` 指向處理目前錯誤相關額外資訊的網址。

links[]

Link

指向處理目前錯誤相關額外資訊的網址。

連結

說明網址連結。

欄位

欄位
`description`	`string` 說明連結提供的內容。
`url`	`string` 連結的網址。

description

string

說明連結提供的內容。

url

string

連結的網址。

LocalizedMessage

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

欄位

欄位
`locale`	`string` 使用的語言代碼遵循 https://www.rfc-editor.org/rfc/bcp/bcp47.txt 中定義的規格。例如：「en-US」、「fr-CH」、「es-MX」
`message`	`string` 上述語言代碼的本地化錯誤訊息。

locale

string

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

message

string

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

PreconditionFailure

說明失敗的先決條件。

舉例來說，如果 RPC 失敗是因為需要確認服務條款，則 PreconditionFailure 訊息可能會列出服務條款違規事項。

欄位

欄位
`violations[]`	`Violation` 說明所有前提條件違規事項。

violations[]

Violation

說明所有前提條件違規事項。

違規事項

用於說明單一前提條件失敗的訊息類型。

欄位

欄位
`type`	`string` PreconditionFailure 的類型。建議使用服務專屬的列舉型別，定義支援的前提條件違規事項主體。例如「TOS」(違反服務條款)。
`subject`	`string` 失敗的主體 (相對於類型)。舉例來說，相對於「TOS」類型，「google.com/cloud」會指出所參照的服務條款。
`description`	`string` 先決條件失敗的原因。開發人員可根據這項說明瞭解如何修正失敗問題。例如「未接受服務條款」。

type

string

PreconditionFailure 的類型。建議使用服務專屬的列舉型別，定義支援的前提條件違規事項主體。例如「TOS」(違反服務條款)。

subject

string

失敗的主體 (相對於類型)。舉例來說，相對於「TOS」類型，「google.com/cloud」會指出所參照的服務條款。

description

string

先決條件失敗的原因。開發人員可根據這項說明瞭解如何修正失敗問題。

例如「未接受服務條款」。

QuotaFailure

說明配額檢查失敗的原因。

舉例來說，如果呼叫專案超過每日上限，服務可能會傳回 QuotaFailure 詳細資料，其中包含專案 ID 和超過配額上限的說明。如果呼叫專案尚未在開發人員控制台中啟用服務，服務可能會傳回專案 ID，並將 service_disabled 設為 true。

如要進一步瞭解如何處理配額失敗問題，請參閱 RetryInfo 和 Help 類型。

欄位

欄位
`violations[]`	`Violation` 說明所有配額違規事項。

violations[]

Violation

說明所有配額違規事項。

違規事項

用於說明單一配額違規事項的訊息類型。例如超出每日配額或自訂配額。

欄位
`subject`	`string` 配額檢查失敗的主體。例如「clientip:」或「project:」。
`description`	`string` 說明配額檢查失敗的原因。用戶可以透過這項說明，在服務的公開說明文件中進一步瞭解配額設定，或透過開發人員控制台找出相關配額限制並進行調整。例如：「服務已停用」或「超過讀取作業的每日限制」。
`api_service`	`string` `QuotaFailure.Violation` 的來源 API 服務。在某些情況下，配額問題並非源自於呼叫的 API 服務，換句話說，呼叫的 API 服務的依附元件可能是 `QuotaFailure` 的原因，而這個欄位會顯示依附元件 API 服務名稱。舉例來說，如果呼叫的 API 是 Kubernetes Engine API (container.googleapis.com)，且 Kubernetes Engine API 本身發生配額違規情形，這個欄位就會是「container.googleapis.com」。另一方面，如果 Kubernetes Engine API 在 Compute Engine API (compute.googleapis.com) 中建立 VM 時發生配額違規情形，這個欄位就會是「compute.googleapis.com」。
`quota_metric`	`string` 違反配額的指標。配額指標是具名的計數器，用於測量用量，例如 API 要求或 CPU。當服務中發生活動 (例如虛擬機器分配作業) 時，可能會影響一或多個配額指標。例如「compute.googleapis.com/cpus_per_vm_family」、「storage.googleapis.com/internet_egress_bandwidth」。
`quota_id`	`string` 違反配額的 ID。也稱為「限制名稱」，這是 API 服務環境中配額的不重複 ID。例如「CPUS-PER-VM-FAMILY-per-project-region」。
`quota_dimensions`	`map<string, string>` 違反配額的維度。系統會針對一組維度強制執行所有非全域配額。配額指標會定義要計算的項目，維度則會指定計數器應增加的方面。舉例來說，「每個區域每個 VM 系列的 CPU 數量」配額會對「compute.googleapis.com/cpus_per_vm_family」指標，以及「region」和「vm_family」維度強制執行限制。如果違規行為發生在「us-central1」區域，且 VM 系列為「n1」，則 quota_dimensions 會是： { "region": "us-central1", "vm_family": "n1", } 如果配額是在全域強制執行，quota_dimensions 一律會是空白。
`quota_value`	`int64` `QuotaFailure`當時的強制配額值。舉例來說，如果 `QuotaFailure`時 CPU 數量的強制配額值為「10」，則這個欄位的值會反映這個數量。
`future_quota_value`	`int64` 違規時推出的新配額值。推出作業完成後，系統會強制使用這個值，取代 quota_value。如果違規時沒有正在進行的推出作業，就不會設定這個欄位。舉例來說，如果違規時正在進行推出作業，將 CPU 配額從 10 個變更為 20 個，則這個欄位的值會是 20。

RequestInfo

包含用戶端在回報錯誤或提供其他形式意見回饋時可附加的要求中繼資料。

欄位

欄位
`request_id`	`string` 不透明的字串，只能由產生該字串的服務解讀。舉例來說，這項 ID 可用於識別服務記錄中的要求。
`serving_data`	`string` 用於處理這項要求的任何資料。舉例來說，加密的堆疊追蹤記錄可傳回給服務供應商進行偵錯。

request_id

string

不透明的字串，只能由產生該字串的服務解讀。舉例來說，這項 ID 可用於識別服務記錄中的要求。

serving_data

string

用於處理這項要求的任何資料。舉例來說，加密的堆疊追蹤記錄可傳回給服務供應商進行偵錯。

ResourceInfo

說明正在存取的資源。

欄位
`resource_type`	`string` 所存取資源類型的名稱，例如「SQL 資料表」、「Cloud Storage 值區」、「檔案」、「Google 日曆」；或是資源的類型 URL，例如「type.googleapis.com/google.pubsub.v1.Topic」。
`resource_name`	`string` 存取的資源名稱。舉例來說，如果目前的錯誤是 `google.rpc.Code.PERMISSION_DENIED`，共用日曆名稱可能為「example.com_4fghdhgsrgh@group.calendar.google.com"」。
`owner`	`string` 資源擁有者 (選填)。例如「user:」或「project:」。
`description`	`string` 說明存取這項資源時發生的錯誤。舉例來說，更新雲端專案可能需要開發人員控制台專案的 `writer` 權限。

RetryInfo

說明用戶端可重試失敗要求的時機。如果錯誤回應缺少這項資訊，用戶端可以忽略此建議或重試。

一律建議用戶端在重試時使用指數輪詢。

用戶端應等待收到錯誤回應後經過 retry_delay 時間，再重試要求。如果重試要求也失敗，用戶端應使用指數輪詢機制，根據 retry_delay 逐步增加重試之間的延遲時間，直到達到重試次數上限或重試延遲時間上限為止。

欄位

欄位
`retry_delay`	`Duration` 用戶端重試相同要求時，至少應等待這麼長的時間。

retry_delay

Duration

用戶端重試相同要求時，至少應等待這麼長的時間。

狀態

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

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

欄位

欄位
`code`	`int32` 狀態碼，應為 `google.rpc.Code` 的列舉值。
`message`	`string` 向開發人員顯示的錯誤訊息，應以英文呈現。所有面向使用者的錯誤訊息都應經過本地化，並透過 `google.rpc.Status.details` 欄位傳送，或是由用戶端加以本地化。
`details[]`	`Any` 包含錯誤詳細資料的訊息清單。這是供 API 使用的一組常用訊息類型。

code

int32

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

message

string

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

details[]

Any

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

Package google.rpc 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

索引

BadRequest

FieldViolation

程式碼

ErrorInfo

說明

連結

LocalizedMessage

PreconditionFailure

違規事項

QuotaFailure

違規事項

RequestInfo

ResourceInfo

RetryInfo

狀態

Package google.rpc