エラーとリトライ

エラーは、安定したマシン可読の error コードと対応する HTTP ステータスを持つ JSON として返されます。

{
  "error": "rate_limited",
  "message": "Too many requests.",
  "retry_after_ms": 850
}

エラーコード

HTTP	error	リトライ？	備考
400	invalid_request	いいえ	パラメータが検証に失敗しました — リクエストを修正してください。
401	missing_api_key / unknown_api_key	いいえ	認証を参照。
403	inactive_api_key / account_blocked	いいえ	キーが無効、またはアカウントが停止されています。
402	insufficient_credits	いいえ	チャージしてください。ボディには required と balance が含まれます。
429	rate_limited	はい、retry_after_ms 後	1 分あたりの上限を超えました。
409	request_in_progress	はい	同一のべき等リクエストがまだ実行中です。
422	（べき等性の衝突）	いいえ	Idempotency-Key が異なるボディで再利用されました。
503	service_temporarily_unavailable / too_many_concurrent_requests	はい、バックオフあり	一時的な容量制限。
504	result_timeout	はい	アップストリームの取得が deadline_ms を超えました。

リトライのガイダンス

• 429 / 503 / 504 / 409 は指数バックオフでリトライしてください。retry_after_ms がある場合は、 リトライ前に少なくともその時間だけ待ってください。
• 400 / 401 / 402 / 403 は決してリトライしないでください — 変更しない限りリクエストは成功しません。
• 公式の SDK はすでに一時的なエラーを自動でリトライし（デフォルトで 2 回）、エラーに retryable フラグを公開します。

便利なレスポンスヘッダー

x-ratelimit-remaining は現在の 1 分間に残っているリクエスト数を報告します。x-idempotent-replay: true は、レスポンスがべき等性キャッシュから再生されたことを示します（再課金されていません）。