コンテンツにスキップ

エラーと再試行

ビジネスエラーは、レスポンスボディのトップレベルで 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 レスポンスヘッダーを記録してください。

ステータス意味アドバイス
400無効なリクエストです。たとえば、選択した設定が利用できません。リクエストを修正してください。再試行は行わないでください。
401資格情報が欠落、無効、期限切れ、または失効しています認証情報を変更する
402残高(負債を差し引いたもの)がジョブのしきい値を超えず、または負の値である場合、APIキーを使用している場合はそのキーの残り予算が不足している可能性があります。残高を追加(またはキーの予算を増額)してから、再度送信してください。
403キーの制限によりこの操作が許可されていない場合(例:翻訳設定は許可されていません)、アカウントが無効化されている場合、または署名済みブラウザで実行する必要がある操作(APIキーの管理など)の場合があります。主要な設定を確認するか、ウェブサイトをご利用ください。
404リソースが存在しない、削除された、または別のアカウントに属している場合(これら3つは見た目上区別できません)。IDを確認してください
409イデポテンシーキーは別のリクエストで使用されており、またはリソースの状態がその操作を許可していません。元の操作をクエリし、その後判断する
410リソースまたはエンドポイントは恒久的に存在しなくなりました。たとえば、廃止されたエンドポイントや、べき等性キーに紐づく削除済みのジョブなどです。再試行しないでください
413ファイルまたはリクエスト本文が上限を超えていますより小さなファイルを使用してください
415サポートされていないファイル形式別の形式を使用してください
422検証に失敗しました。または、ファイルが空であるか、処理すべき内容が含まれていません。フィールドを修正してください。自動再試行は行わないでください。
429レート、キューのサイズ、または予算に制限あり以下をご覧ください
5xx一時的なサービスエラー最大試行回数を設定した指数バックオフ
code意味どうすればよいですか
RATE_LIMITEDリクエストが多すぎますRetry-After を待ってから再試行してください
CONCURRENCY_LIMITEDファイル変換ジョブが過剰にキューイングされていますRetry-After が完了するか、一部のジョブが終了するまで待機します。
AUTH_API_KEY_QUOTA_EXCEEDEDキーの予算が使い果たされました予算が増額されるまで再試行しないでください

Retry-Afterを含まない 429 は、指数バックオフで処理する必要があります。

  • クエリは直接再試行できます。
  • 作成リクエストを再試行する際は、同じ Idempotency-Key と完全に同一の本文を再利用し、新しい送信ごとに新しいキーを使用してください。
  • アップロードに失敗した場合は、新しいアップロードアドレスを要求してください。
  • 各リクエストに対して接続タイムアウト、読み取りタイムアウト、および総タイムアウトを設定し、再試行にランダムなジッターを加え、試行回数に上限を設けます。
import random
import 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())