ステータスコード
gRPCで使用されるステータスコードについて説明します。
ステータスコード
gRPCで使用されるステータスコードについて説明します。
概要
すべてのRPCは、クライアントに返される`status`という結果を持ちます。 `status`オブジェクトは、整数コードと文字列エラー記述で構成されます。サーバー側（またはライブラリレベルのエラーの場合はgRPCライブラリ）は、特定のRPCに対して返すステータスを選択します。アプリケーションは、以下に定義されている値のみを使用する必要があります。
エラーが発生した場合、gRPCライブラリは対応する`status`を生成することがあります。ライブラリは、クライアント側またはサーバー側のいずれかでこれを行う場合があります。定義済みのステータスコードのサブセットのみがgRPCライブラリによって生成されます。これにより、アプリケーションは、表示される他のコードが実際にアプリケーションによって返されたことを確認できます（ただし、サーバー側でgRPCライブラリによって生成されたコードの1つを返すことも可能です）。
ステータスコードの使用方法については、エラー処理ユーザーガイドを参照してください。
ステータスコード一覧
gRPCは、RPC APIの一部として明確に定義されたステータスコードのセットを使用します。
次のステータスコードはライブラリによって生成されることはなく、ユーザーコードによってのみ生成されます
- INVALID_ARGUMENT（無効な引数）
- NOT_FOUND（見つかりません）
- ALREADY_EXISTS（既に存在します）
- FAILED_PRECONDITION（前提条件の失敗）
- ABORTED（中止）
- OUT_OF_RANGE（範囲外）
- DATA_LOSS（データ損失）
ステータスコード一覧
| コード | ID | 説明 |
|---|---|---|
| OK | 0 | エラーではありません。成功時に返されます。 |
| CANCELLED（キャンセル済み） | 1 | 操作はキャンセルされました。通常は呼び出し元によってキャンセルされます。 |
| UNKNOWN（不明） | 2 | 不明なエラー。たとえば、別のアドレス空間から受信した`Status`値がこのアドレス空間で認識されていないエラー空間に属している場合に、このエラーが返されることがあります。また、十分なエラー情報を返さないAPIによって発生したエラーは、このエラーに変換される場合があります。 |
| INVALID_ARGUMENT（無効な引数） | 3 | クライアントが無効な引数を指定しました。これは`FAILED_PRECONDITION`とは異なります。 `INVALID_ARGUMENT`は、システムの状態に関係なく問題のある引数（例：不正なファイル名）を示します。 |
| DEADLINE_EXCEEDED（期限超過） | 4 | 操作が完了する前に期限が切れました。システムの状態を変更する操作の場合、操作が正常に完了した場合でも、このエラーが返されることがあります。たとえば、サーバーからの正常な応答が長時間遅延した可能性があります |
| NOT_FOUND（見つかりません） | 5 | 要求されたエンティティ（例：ファイルまたはディレクトリ）が見つかりませんでした。サーバー開発者への注意：段階的な機能ロールアウトや文書化されていない許可リストなど、クラス全体のユーザーに対してリクエストが拒否された場合は、`NOT_FOUND`を使用できます。ユーザーベースのアクセス制御など、クラス内の 一部の ユーザーに対してリクエストが拒否された場合は、`PERMISSION_DENIED`を使用する必要があります。 |
| ALREADY_EXISTS（既に存在します） | 6 | クライアントが作成しようとしたエンティティ（例：ファイルまたはディレクトリ）は既に存在します。 |
| PERMISSION_DENIED（権限拒否） | 7 | 呼び出し元には、指定された操作を実行する権限がありません。`PERMISSION_DENIED`は、一部のリソースを使い果たしたために発生した拒否には使用しないでください（これらのエラーには`RESOURCE_EXHAUSTED`を使用してください）。呼び出し元を識別できない場合は、`PERMISSION_DENIED`を使用しないでください（これらのエラーには`UNAUTHENTICATED`を使用してください）。このエラーコードは、リクエストが有効であること、またはリクエストされたエンティティが存在すること、または他の前提条件を満たしていることを意味するものではありません。 |
| RESOURCE_EXHAUSTED（リソース исчерпан） | 8 | 一部のリソースが使い果たされました。ユーザーごとのクォータ、またはファイルシステム全体の容量不足などが考えられます。 |
| FAILED_PRECONDITION（前提条件の失敗） | 9 | システムが操作の実行に必要な状態にないため、操作は拒否されました。たとえば、削除するディレクトリが空でない場合、rmdir操作がディレクトリ以外に適用された場合などです。サービス実装者は、`FAILED_PRECONDITION`、`ABORTED`、`UNAVAILABLE`のいずれかを選択するために、次のガイドラインを使用できます。(a) クライアントが失敗した呼び出しのみを再試行できる場合は、`UNAVAILABLE`を使用します。(b) クライアントがより高いレベルで再試行する必要がある場合は、`ABORTED`を使用します（例：クライアントが指定したtest-and-setが失敗し、クライアントが読み取り-変更-書き込みシーケンスを再開する必要があることを示している場合）。(c) システムの状態が明示的に修正されるまでクライアントが再試行しない場合は、`FAILED_PRECONDITION`を使用します。たとえば、「rmdir」がディレクトリが空でないために失敗した場合、クライアントはディレクトリからファイルが削除されない限り再試行しないため、`FAILED_PRECONDITION`を返す必要があります。 |
| ABORTED（中止） | 10 | 操作は中止されました。通常は、シーケンサーチェックの失敗やトランザクションの中止などの同時実行の問題が原因です。`FAILED_PRECONDITION`、`ABORTED`、`UNAVAILABLE`のいずれかを選択するためのガイドラインについては、上記を参照してください。 |
| OUT_OF_RANGE（範囲外） | 11 | 操作は有効な範囲を超えて試行されました。例：ファイルの終わりを超えてシークまたは読み取りを行っています。`INVALID_ARGUMENT`とは異なり、このエラーは、システムの状態が変化した場合に修正される可能性のある問題を示します。たとえば、32ビットファイルシステムは、[0,2^32-1]の範囲にないオフセットで読み取るように要求された場合に`INVALID_ARGUMENT`を生成しますが、現在のファイルサイズを超えるオフセットから読み取るように要求された場合は`OUT_OF_RANGE`を生成します。`FAILED_PRECONDITION`と`OUT_OF_RANGE`の間には、かなりの重複があります。呼び出し元がスペースを反復処理している場合に`OUT_OF_RANGE`エラーを簡単に検出して完了したことを検出できるように、適用できる場合は`OUT_OF_RANGE`（より具体的なエラー）を使用することをお勧めします。 |
| UNIMPLEMENTED（未実装） | 12 | 操作は実装されていないか、このサービスではサポート/有効化されていません。 |
| INTERNAL（内部） | 13 | 内部エラー。これは、基盤となるシステムによって予期される一部の不変条件が壊れていることを意味します。このエラーコードは重大なエラーのために予約されています。 |
| UNAVAILABLE（利用不可） | 14 | サービスは現在利用できません。これは、一時的な状態である可能性が高く、バックオフを使用して再試行することで修正できます。べき等でない操作を再試行することが常に安全であるとは限らないことに注意してください。 |
| DATA_LOSS（データ損失） | 15 | 回復不能なデータの損失または破損。 |
| UNAUTHENTICATED（未認証） | 16 | リクエストには、操作の有効な認証資格情報がありません。 |
最終更新日 2024年2月29日: ステータスコードユーザーガイド (#1263) (fb661d4)