エラーと再試行

エラーメッセージの言語

人が読むエラーメッセージは、呼び出し側が選んだ言語で返せます。対象はレスポンスの msg、失敗したタスクの errorMessage（recordInfo と webhook 通知の両方）、互換 API のエラーオブジェクトに含まれる error.message（OpenAI・Anthropic・Google Gemini のどの形式でも同じ）の 3 つで、既定は英語です。対応する言語コードは en、zh-Hant、ja、ko、de、fr、es、pt-BR、ru です。

変わるのは人が読む文だけです。code と errorCode、OpenAI 互換レイヤーの type と code、Gemini 互換レイヤーの code と status、そしてフィールド名は、言語によって変わりません。処理の分岐は必ずコードで行い、文言を解析しないでください。ログやアラートには code と request_id を記録することをおすすめします。実際に使われた言語は、レスポンスヘッダー Content-Language で確認できます。たとえば同じ 40201（残高不足）の msg は、既定では「Insufficient balance」ですが、Accept-Language: ja を付けると日本語になります。code は 40201 のままです。

言語は次の優先順で決まります。

• リクエストヘッダー Accept-Language：そのリクエストだけに適用されます。標準の HTTP の重み付けに従い、認識できる言語のうち q 値が最も高いものを選びます。de-DE は de、pt-PT は pt-BR、zh-TW・zh-HK・zh-Hant は zh-Hant として扱います。中国語は繁体字のみの提供のため、zh-CN と zh-Hans はどの言語にも一致せず、次の候補に進みます。* は指定なしとみなします。
• アカウント設定：コンソールの「設定 → API エラーの言語」です。このアカウントの API キーで送信され、認識できる Accept-Language を含まないリクエストに適用されます。サーバー向けの SDK の多くや curl は既定でこのヘッダーを送らないため、実際にはこちらが最もよく使われます。webhook 通知にはリクエストヘッダーがないため、常にアカウント設定に従います。
• どちらもない場合は英語です。

# Default: no Accept-Language, no account setting
HTTP/1.1 402 Payment Required
Content-Language: en

{ "code": 40201, "msg": "Insufficient balance", "request_id": "req_…" }

# The same request with one extra header
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
  -H "Accept-Language: ja" \
  --data "$TASK_PAYLOAD"

HTTP/1.1 402 Payment Required
Content-Language: ja

{ "code": 40201, "msg": "残高が不足しています", "request_id": "req_…" }

再試行しないエラー

400、401、403、404、40201、40202、40301〜40303 は、入力、認証情報、権限、残高、上限を修正しない限り改善しません。413 は本文が大きすぎるため再試行せず、本文を小さくするかメディアアップロード手順を使います。

再試行できるエラー

429 は Retry-After に従います。HTTP 500 / 503 またはビジネスコード 500 / 50301 は指数バックオフとジッターで再試行します。409 は操作固有です。メディアの pending と、同じ Idempotency-Key・同じ payload のまま起きたまれな createTask 競合だけを待って再試行します。別の payload に使ったキーの競合は再試行しません。

タスク作成のネットワーク再試行では同じ Idempotency-Key を再利用します。異なる payload に同じキーを使うと 409 になります。

課金との関係

作成前に拒否されたリクエストは課金されません。作成後の failed・expired と履歴 canceled は hold が全額解放されます。新しい受理済みタスクは取り消せず、succeeded のみ実使用量で精算されます。