エラー処理
このセクションでは、Zerobus Ingest API によってエラーが返される方法と、クライアントがエラーを処理する方法について説明します。
エラー応答の形式
REST (JSON)
エラー応答は、適切な HTTP 状態コードを含む JSON として返されます。
{
"error_code": "NOT_FOUND",
"message": "Table \"catalog.schema.table\" cannot be found."
}
| フィールド | タイプ | 説明 |
|---|---|---|
| エラーコード | 文字列 | エラーのカテゴリを識別する、コンピューターが読み取り可能なエラー コード。 これを使用して、プログラムでエラーを処理する方法を決定します。 |
| メッセージ | 文字列 | 人が判読できるエラーの説明。 トラブルシューティング用の追加の診断情報が含まれる場合があります。 このフィールドはプログラムで解析しないでください。形式は予告なく変更される可能性があります。 |
gPRC
エラー応答では、応答トレーラーを介して配信される標準の gRPC 状態コードが使用されます。
| トレーラー | 説明 |
|---|---|
| grpc-status | 数値状態コード (例えば、3の場合のINVALID_ARGUMENT)。 これを使用して、プログラムでエラーを処理する方法を決定します。 |
| grpcメッセージ | 人が判読できるエラーの説明。 トラブルシューティング用の追加の診断情報が含まれる場合があります。 このフィールドはプログラムで解析しないでください。形式は予告なく変更される可能性があります。 |
エラー コード
次の表に、Zerobus Ingest API によって返されるすべてのエラー コード、対応するプロトコル レベル のコード、推奨されるクライアント動作を示します。
クライアント エラー
これらのエラーは、要求に問題があることを示しています。 要求を変更せずに再試行しないでください。
| エラー コード (REST) | gRPC コード | HTTP 状態 | 説明 | 推奨される操作 |
|---|---|---|---|---|
INVALID_PARAMETER_VALUE |
INVALID_ARGUMENT(3) |
400 | 要求に無効な入力または形式が正しくない入力 (必須フィールドが見つからない、スキーマが無効、サポートされていないレコード形式など) が含まれています。 | 要求を修正して再送信します。 無効なパラメーターの詳細については、 message フィールドを調べます。 |
NOT_FOUND |
NOT_FOUND(5) |
404 | 要求されたリソースが存在しません。 たとえば、指定したテーブルが見つかりません。 | リソース名が正しいことと、リソース名が存在することを確認します。 |
NOT_IMPLEMENTED |
UNIMPLEMENTED(12) |
501 | 要求された操作はサポートされていません。 たとえば、テーブルではサポートされていない機能またはデータ形式が使用されます。 | 再試行しないでください。 サポートされていない内容の詳細については、 message フィールドを参照してください。 |
認証と承認のエラー
これらのエラーは、呼び出し元の ID またはアクセス許可に関する問題を示しています。 同じ資格情報で再試行しないでください。
| エラー コード (REST) | gRPC コード | HTTP 状態 | 説明 | 推奨される操作 |
|---|---|---|---|---|
UNAUTHENTICATED |
UNAUTHENTICATED(16) |
401 | 要求に有効な認証資格情報がありません。 トークンが見つからない、空、期限切れ、または無効である可能性があります。 | 有効な認証トークンを更新または指定して、再試行します。 |
PERMISSION_DENIED |
PERMISSION_DENIED(7) |
403 | 呼び出し元には、指定されたリソースに対して要求された操作を実行するための十分な特権がありません。 | 呼び出し元がターゲット リソースに必要な特権 (たとえば、 MODIFY、 SELECT、 USE_CATALOG、 USE_SCHEMA) を持っていることを確認します。 |
サーバー エラー
これらのエラーは、サーバー側の問題を示しています。 指数バックオフとジッターを使用して再試行します。
| エラー コード (REST) | gRPC コード | HTTP 状態 | 説明 |
|---|---|---|---|
UNAVAILABLE |
UNAVAILABLE(14) |
503 | サービスは一時的に要求を処理できません。 これは通常、一時的な状態です。 指数バックオフとジッターを使用して再試行します。 |
RESOURCE_EXHAUSTED |
RESOURCE_EXHAUSTED(8) |
429 | リソースの制限により、サービスが要求を拒否しています。 可能であれば、要求の同時実行を減らしてください。 指数バックオフとジッターを使用して再試行します。 |
INTERNAL_ERROR |
INTERNAL_ERROR(13) |
500 | 予期しない内部エラーが発生しました。 再試行しないでください。 サポートに問い合わせ、診断のための完全なエラー応答を提供してください。 |