錯誤與錯誤處理機制

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

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

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

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

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

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

元素 說明
code HTTP 狀態碼，通常用於識別要求失敗情形。
message 要求失敗的相關具體資訊。
status Google API 的標準化錯誤代碼 (google.rpc.Code)。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 伺服器傳回錯誤。 使用指數輪詢重試。