Zerobus の取り込みエラー処理

エラー処理

このセクションでは、Zerobus Ingest API によってエラーが返される方法と、クライアントがエラーを処理する方法について説明します。

エラー応答は、適切な HTTP ステータスコードを含む JSON として返されます。

JSON
{
  "error_code": "NOT_FOUND",
  "message": "Table \"catalog.schema.table\" cannot be found."
}

フィールド	Type	説明
エラーコード	string	障害のカテゴリを識別する、機械で読み取り可能なエラーコード。これを使用して、プログラムでエラーを処理する方法を決定します。
message	string	人間が読める形式のエラーの説明。トラブルシューティングのための追加の診断情報が含まれる場合があります。このフィールドをプログラムで解析しないでください。形式は予告なく変更される可能性があります。

エラー応答では、応答トレーラー経由で配信される標準の gRPC ステータスコードが使用されます。

トレーラー	説明
grpc-ステータス	数値のステータスコード (例: `INVALID_ARGUMENT`の場合は`3` )。これを使用して、プログラムでエラーを処理する方法を決定します。
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	予期しない内部エラーが発生しました。再試行しないでください。サポートに連絡し、診断のために完全なエラー応答を提供してください。