このページでは、Spanner のエラーコードと、これらのエラーに対処するために推奨される対応について説明します。Spanner などの Google API では、google.rpc.Code によって定義された正規のエラーコードを使用します。
Spanner リクエストが成功すると、API はリクエストされたデータとともに、HTTP 200 OK ステータス コードをレスポンスの本文で返します。
リクエストが失敗すると、Spanner API は失敗の概要を表す 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 フィールドに表示されます。
| Error code（エラーコード） | 説明 | 推奨される対応 |
|---|---|---|
ABORTED |
オペレーションは、通常、シーケンサー チェックの失敗、またはトランザクションの中止などの同時実行の問題のために中止されています。リクエストが別のリクエストと競合していることを示します。 | 非トランザクション commit の場合: リクエストを再試行するか、競合がなくなるようにエンティティを構築します。 トランザクション commit に含まれるリクエスト: トランザクション全体を再試行するか、競合がなくなるようにエンティティを構築します。 |
ALREADY_EXISTS |
クライアントが作成しようとしたエンティティはすでに存在します（たとえば、既存の主キーを持つ行を挿入する）。 | 問題を解決してから再試行します。 |
CANCELLED |
オペレーションがキャンセルされました。通常、キャンセルは呼び出し元により行われます。 | オペレーションを再試行してください。 |
DEADLINE_EXCEEDED |
オペレーションが完了する前に期限が切れました。 | 期限が十分かどうかを確認してください。レスポンスが使用される実際の時間に対応する期限を使用します。システムの状態を変更するオペレーションの場合、オペレーションが正常に完了してもエラーが返されることがあります。 ヒントについては、期限超過エラーのトラブルシューティングをご覧ください。 |
FAILED_PRECONDITION |
リクエストの前提条件が満たされなかったため、オペレーションが拒否されました。エラー レスポンスのメッセージ フィールドで、失敗した前提条件に関する情報が提供されます。考えられる原因の 1 つとして、クエリが未定義のインデックスを必要としていることが挙げられます。 | 問題を解決してから再試行します。 |
INTERNAL |
サーバーがエラーを返しました。 基盤となるシステムで予期される一部の不変条件から逸脱しています。 | エラーの具体的な状況と原因を理解している場合を除き、再試行しないでください。 |
INVALID_ARGUMENT |
クライアントが無効な値を指定しました。エラー レスポンスのメッセージ フィールドで、無効であった値を特定する情報が提供されます。 | 問題を解決してから再試行します。 |
NOT_FOUND |
エンティティの更新やテーブルまたは列のクエリなど、リクエストされたエンティティが存在しないことを示します。 | 問題を解決してから再試行します。 |
OUT_OF_RANGE |
オペレーションが有効な範囲を超えて試行されました。 | 問題を解決してから再試行します。 |
PERMISSION_DENIED |
リクエストの実行がユーザーに許可されませんでした。 | 問題を解決してから再試行します。 |
RESOURCE_EXHAUSTED |
リソースが不足しています。プロジェクトが割り当てを超えているか、ファイル システム全体で容量が不足している可能性があります。 | Spanner またはプロジェクトの割り当てを超えていないことを確認します。割り当てを超えている場合は、問題を解決してから再試行してください。 そうでない場合は、指数バックオフを使用して再試行します。 |
UNAUTHENTICATED |
リクエストにはオペレーションに有効な認証情報がありません。 | 問題を解決してから再試行します。 |
UNAVAILABLE |
現在サーバーを使用できません | 指数バックオフを使用して再試行します。 非べき等オペレーションの再試行が常に安全であるとは限りません。 |
UNIMPLEMENTED |
オペレーションが実装されていないか、このサービスでサポートまたは有効にされていません。 | 問題を解決してから再試行します。 |
UNKNOWN |
サーバーが不明なエラーを返しました。十分なエラー情報を返さない API によって発生したエラーは、このエラーに変換できます。 | リクエストが安全であることを確認します。その後、指数バックオフを使用して再試行します。 |