本頁面說明 Spanner 錯誤代碼，以及處理這些錯誤的建議做法。Google API (包括 Spanner) 會使用由 google.rpc.Code 定義的標準錯誤代碼。
Spanner 要求若成功，API 會在回應本文中傳回 HTTP 200 OK 狀態碼及所要求的資料。
若要求失敗，Spanner API 會傳回 HTTP 4xx 或 5xx 狀態碼，此狀態碼通常能識別失敗，也能識別回應，此回應針對導致失敗的錯誤提供更多具體資訊。
回應物件包含單一欄位 error，其值包含以下元素：
| 元素 | 說明 |
|---|---|
code |
HTTP 狀態碼，通常用於識別要求失敗情形。 |
message |
要求失敗的相關具體資訊。 |
status |
Google API 的標準化錯誤代碼 (google.rpc.Code)。Spanner API 可能會傳回的代碼列於「錯誤代碼」一節中。 |
如果以 application/x-protobuf 內容類型提出的要求發生錯誤，會傳回序列化的 google.rpc.Status 訊息做為酬載。
錯誤代碼
如要分類錯誤，建議檢查標準化錯誤代碼 (google.rpc.Code) 的值。在 JSON 錯誤中，此代碼會出現在 status 欄位。在 application/x-protobuf 錯誤中，則出現在 code 欄位。
| 錯誤代碼 | 說明 | 建議做法 |
|---|---|---|
ABORTED |
作業已取消，原因通常是排序器檢查失敗或交易取消等並行問題。表示該項要求與另一項要求衝突。 | 非交易型修訂： 重試一次要求，或是調整實體結構以解決衝突。 若要求屬於交易型修訂： 重試整筆交易，或者以減少內容的方式調整實體架構。 |
ALREADY_EXISTS |
用戶端嘗試建立的實體已存在 (例如，插入具有現有主鍵的資料列)。 | 未修正問題前請勿重試。 |
CANCELLED |
作業已取消，一般由呼叫者取消。 | 請重試作業。 |
DEADLINE_EXCEEDED |
在作業完成前已過期。 | 調查是否有足夠的時間完成作業。請使用與實際回應時間相對應的期限。請注意，針對會變更系統狀態的作業，即使作業順利完成也有可能會傳回錯誤， 如需提示，請參閱「排解逾時錯誤」。 |
FAILED_PRECONDITION |
作業已遭拒絕，因為未達到該項要求的先決條件。錯誤回應中的訊息欄位說明未達到的先決條件。舉例來說，從已超過最大時間戳記過時程度的時間戳記讀取或查詢。 | 未修正問題前請勿重試。 |
INTERNAL |
伺服器傳回錯誤。基礎系統預期的某些不變量已損毀。 | 除非您瞭解錯誤的具體情況和原因，否則請勿重試。 |
INVALID_ARGUMENT |
用戶端指定的值無效。錯誤回應中的訊息欄位說明無效值的相關資訊。 | 未修正問題前請勿重試。 |
NOT_FOUND |
表示某些要求的實體 (例如更新實體或查詢資料表或資料欄) 不存在。 | 未修正問題前請勿重試。 |
OUT_OF_RANGE |
嘗試執行的作業超出有效範圍。 | 未修正問題前請勿重試。 |
PERMISSION_DENIED |
使用者沒有提出要求的權限。 | 未修正問題前請勿重試。 |
RESOURCE_EXHAUSTED |
已耗盡某些資源。 在管理員層面，專案可能已超過配額，或整個檔案系統的空間不足。 在資料層面，如果 Spanner 節點超載，就可能發生這種情況。 |
針對管理員平面，請確認您未超過 Spanner 或專案配額。如果您已超出配額，請申請提高配額，或是等待配額重設後再試一次。請將重試次數設為使用指數型退避。 針對資料層，請確認 Spanner 節點未超出容量。Spanner 會在用戶端程式庫中重試這些錯誤。如果所有重試都失敗，請參閱「流程控制機制錯誤」。 一般來說，如果應用程式發生 RESOURCE_EXHAUSTED 錯誤，請將情況視為 UNAVAILABLE 錯誤，並透過指數輪詢重試。 |
UNAUTHENTICATED |
要求中不含作業的有效驗證憑證。 | 未修正問題前請勿重試。 |
UNAVAILABLE |
伺服器無法使用。 | 使用指數輪詢重試。請注意，重試非冪等操作不一定安全。 |
UNIMPLEMENTED |
未實作作業或作業在此服務中不受支援/未啟用。 | 未修正問題前請勿重試。 |
UNKNOWN |
伺服器傳回不明錯誤。由 API 發出但未傳回充分錯誤資訊的錯誤，也可能會轉換為此錯誤。 | 請確認您的要求安全無虞。然後以指數輪詢方式重試。 |
流量控制機制錯誤
在下列情況下，Spanner 可能會啟用流量控制機制，以免過載：
- Spanner 節點的 CPU 使用率偏高。如果您懷疑要求會導致 CPU 使用率升高，可以使用 CPU 使用率指標來調查問題。
- 可能會出現熱點，導致要求的處理時間增加。如果您懷疑要求會造成熱點，請參閱「在資料庫中找出熱點」一文，瞭解問題所在。詳情請參閱「按鍵視覺化工具」。
下列用戶端程式庫支援流程控制機制：
使用流量控制機制後，要求完成的整體時間不會增加。如果沒有這項機制，Spanner 會在處理要求前等待，並最終傳回 DEADLINE_EXCEEDED 錯誤。
當流量控制機制啟用時，Spanner 會將要求推送回用戶端以便重試。如果重試耗用使用者提供的整個期限，用戶端就會收到 RESOURCE_EXHAUSTED 錯誤。如果 Spanner 預估要求的處理時間過長，就會傳回這個錯誤。錯誤會傳播流量控制，而 Spanner 會重試傳送至用戶端的要求，而不是在內部累積重試次數。這可讓 Spanner 避免累積額外的資源耗用量。