エラーと冪等性
標準エラー、再試行、レート制限、重複防止。
エラーは application/problem+json、実際の HTTP ステータス、request_id を使用します。
作成には 8〜128 文字の Idempotency-Key が必要です。サーバーは Key の HMAC とリクエスト指紋だけを保存します。同じ Key／本文は元のタスクを返し、同じ Key／異なる本文は 409 idempotency_conflict、処理中なら 409 request_in_progress を返します。自動再試行で新しい Key を作らないでください。
主なコード：invalid_api_key、invalid_api_key_rate_limited、api_key_expired、insufficient_scope、validation_error、unsupported_model、unsupported_parameter、input_url_not_allowed、insufficient_credits、payment_required、account_suspended、network_not_allowed、rate_limit_exceeded、concurrency_limit_exceeded、provider_unavailable、service_unavailable。
同一 IP から無効な認証情報が繰り返された場合も制限され、保存するのは Pepper HMAC 済み IP 指紋だけです。
ネットワーク障害、429、503 はバックオフし、同じ本文・同じ Key で再試行できます。Provider の結果を確認できない場合、API は盲目的な再送を拒否します。
再試行前に必ず Retry-After header に従ってください。