エラーと再試行
ビジネスエラーは、レスポンスボディのトップレベルで code および message を返します。detail は通常 message と同じですが、以下のように異なる短い説明である場合もあります。ユーザーには message を表示してください。メッセージは中国語です:
{ "code": "CONCURRENCY_LIMITED", "message": "排队中的文件已达上限(1000 个),请等部分文件翻译完成后再提交", "detail": "排队文件完成一部分后可继续提交"}いくつかのビジネスエラーは code のみを返します。検証失敗は 422 を返し、detail にフィールドエラーの一覧が含まれます。
{ "detail": [ { "loc": ["body", "target_lang"], "msg": "Field required", "type": "missing" } ]}エラーはまず HTTP ステータスで処理し、次に code で処理します。多くのエラーは汎用の UNKNOWN_ERROR のみを返し、特定の code を伴うのは一部のケース(下記の 429 ケースなど)に限られます。トラブルシューティングのために X-Request-Id レスポンスヘッダーを記録してください。
HTTP ステータス
Section titled “HTTP ステータス”| ステータス | 意味 | アドバイス |
|---|---|---|
400 | 無効なリクエストです。たとえば、選択した設定が利用できません。 | リクエストを修正してください。再試行は行わないでください。 |
401 | 資格情報が欠落、無効、期限切れ、または失効しています | 認証情報を変更する |
402 | 残高(負債を差し引いたもの)がジョブのしきい値を超えず、または負の値である場合、APIキーを使用している場合はそのキーの残り予算が不足している可能性があります。 | 残高を追加(またはキーの予算を増額)してから、再度送信してください。 |
403 | キーの制限によりこの操作が許可されていない場合(例:翻訳設定は許可されていません)、アカウントが無効化されている場合、または署名済みブラウザで実行する必要がある操作(APIキーの管理など)の場合があります。 | 主要な設定を確認するか、ウェブサイトをご利用ください。 |
404 | リソースが存在しない、削除された、または別のアカウントに属している場合(これら3つは見た目上区別できません)。 | IDを確認してください |
409 | イデポテンシーキーは別のリクエストで使用されており、またはリソースの状態がその操作を許可していません。 | 元の操作をクエリし、その後判断する |
410 | リソースまたはエンドポイントは恒久的に存在しなくなりました。たとえば、廃止されたエンドポイントや、べき等性キーに紐づく削除済みのジョブなどです。 | 再試行しないでください |
413 | ファイルまたはリクエスト本文が上限を超えています | より小さなファイルを使用してください |
415 | サポートされていないファイル形式 | 別の形式を使用してください |
422 | 検証に失敗しました。または、ファイルが空であるか、処理すべき内容が含まれていません。 | フィールドを修正してください。自動再試行は行わないでください。 |
429 | レート、キューのサイズ、または予算に制限あり | 以下をご覧ください |
5xx | 一時的なサービスエラー | 最大試行回数を設定した指数バックオフ |
429の処理
Section titled “429の処理”code | 意味 | どうすればよいですか |
|---|---|---|
RATE_LIMITED | リクエストが多すぎます | Retry-After を待ってから再試行してください |
CONCURRENCY_LIMITED | ファイル変換ジョブが過剰にキューイングされています | Retry-After が完了するか、一部のジョブが終了するまで待機します。 |
AUTH_API_KEY_QUOTA_EXCEEDED | キーの予算が使い果たされました | 予算が増額されるまで再試行しないでください |
Retry-Afterを含まない 429 は、指数バックオフで処理する必要があります。
- クエリは直接再試行できます。
- 作成リクエストを再試行する際は、同じ
Idempotency-Keyと完全に同一の本文を再利用し、新しい送信ごとに新しいキーを使用してください。 - アップロードに失敗した場合は、新しいアップロードアドレスを要求してください。
- 各リクエストに対して接続タイムアウト、読み取りタイムアウト、および総タイムアウトを設定し、再試行にランダムなジッターを加え、試行回数に上限を設けます。
import randomimport time
for attempt in range(5): response = call_api() if response.status_code not in {429, 500, 502, 503, 504}: break if response.status_code == 429 and response.json().get("code") == "AUTH_API_KEY_QUOTA_EXCEEDED": break retry_after = response.headers.get("Retry-After") delay = float(retry_after) if retry_after else min(2 ** attempt, 16) time.sleep(delay + random.random())