錯誤與錯誤處理機制

Cloud Firestore (Datastore 模式) 要求若成功,API 會在回應主體中傳回 HTTP 200 OK 狀態碼及所要求的資料。

若要求失敗,Cloud Datastore API 會傳回 HTTP 4xx5xx 狀態碼,此狀態碼通常能識別失敗,也能識別回應,此回應針對導致失敗的錯誤提供更多具體資訊。

本頁面其餘部分說明錯誤的結構、列舉特定錯誤代碼,另也針對處理錯誤的方式提出建議。

以下是 JSON 要求錯誤回應的結構:

{
  "error": {
    "code": "integer",
    "message": "string",
    "status": "string"
  }
}

回應物件包含單一欄位 error,此欄位的值含以下元素:

元素 說明
code HTTP 狀態碼,通常用於識別要求失敗情形。
message 要求失敗的相關具體資訊。
status Google API 的標準化錯誤代碼 (google.rpc.Code)。Cloud Datastore API 可能會傳回的代碼列於錯誤代碼一節中。

以下舉例說明 JSON 要求的錯誤回應:

{
  "error": {
    "code": 400,
    "message": "Key path is incomplete: [Person: null]",
    "status": "INVALID_ARGUMENT"
  }
}

application/x-protobuf 內容類型提出的要求若發生錯誤,會傳回一則序列化的 google.rpc.Status 訊息做為酬載。

錯誤代碼

如要分類錯誤,建議檢查標準化錯誤代碼 (google.rpc.Code) 的值。在 JSON 錯誤中,此代碼會出現在 status 欄位。在 application/x-protobuf 錯誤中,則出現在 code 欄位。

標準化錯誤代碼 說明 建議做法
ABORTED 表示該項要求與另一項要求衝突。 非交易型修訂:
重試一次要求,或是調整實體結構以解決衝突。

若要求屬於交易型修訂:
重試整筆交易,或者以減少內容的方式調整實體架構。
ALREADY_EXISTS 表示該項要求嘗試插入已經存在的實體。 未修正問題前請勿重試。
DEADLINE_EXCEEDED 超過伺服器上設定的期限。 使用指數輪詢重試。
FAILED_PRECONDITION 表示未達到該項要求的先決條件。錯誤回應中的訊息欄位說明未達到的先決條件。可能原因之一是所執行的查詢必須要有索引,但尚未定義任何索引。 未修正問題前請勿重試。
INTERNAL 伺服器傳回錯誤。 此項要求最多只能重試一次。
INVALID_ARGUMENT 表示要求參數有一個無效值。錯誤回應中的訊息欄位說明無效值的相關資訊。 未修正問題前請勿重試。
NOT_FOUND 表示該項要求嘗試更新不存在的實體。 未修正問題前請勿重試。
PERMISSION_DENIED 表示使用者不具提出要求的權限。 未修正問題前請勿重試。
RESOURCE_EXHAUSTED 表示使用者已超出專案配額。 未修正問題前請勿重試。如需瞭解關於提高專案配額的詳細資訊,請參閱定價與配額
UNAUTHENTICATED 表示此項要求不具有效的驗證憑證。 未修正問題前請勿重試。
UNAVAILABLE 伺服器傳回錯誤。 使用指數輪詢重試。