ステータスコード
gRPCで使用されるステータスコードについて説明します。
ステータスコード
gRPCで使用されるステータスコードについて説明します。
概要
すべてのRPCは、クライアントに返されるstatusをもたらします。statusオブジェクトは、整数コードと文字列のエラー説明で構成されます。サーバー側（またはライブラリレベルのエラーの場合はgRPCライブラリ）が、指定されたRPCのステータスを選択します。アプリケーションは、以下に定義された値のみを使用する必要があります。
エラー状況が発生した場合、gRPCライブラリは対応するstatusを生成することがあります。ライブラリは、クライアント側またはサーバー側のいずれかでこれを行う可能性があります。定義済みのステータスコードのサブセットのみがgRPCライブラリによって生成されます。これにより、アプリケーションは、目にする他のコードが実際にアプリケーションによって返されたものであることを確信できます（ただし、サーバー側がgRPCライブラリによって生成されたコードのいずれかを返すことも可能です）。
ステータスコードの使用方法については、エラー処理ユーザーガイドを参照してください。
ステータスコードの完全なリスト
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を使用します（例：クライアント指定のテスト・アンド・セットが失敗し、クライアントが読み取り・修正・書き込みシーケンスを再開する必要があることを示唆する場合）。（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年8月21日: DEADLINE_EXCEEDED説明の完全な文 (status-codes.md #1348) (081383d)