Skip to content
PleumRouter
始める

エラーコード

エラーは HTTP ステータスコード・detail.error の機械判読コード・ドキュメント化されたレスポンス形式で返されます。

ステータスコード#

コード名前説明
400Bad Request不正なリクエスト。未対応のモデル ID（類似モデルの提案付き）、モデル別パラメータ制約の違反（duration・解像度・参照画像数など）、キーの許可モデル外へのアクセスなど。
401UnauthorizedAPI キーの欠落・無効・期限切れ、または削除されたアカウント。
402Payment Requiredクレジット不足または予算・トークン上限の超過。コードごとに解決方法が異なります（下の機械判読コード表を参照）。
403Forbiddenアクセス拒否。キーの IP 許可リスト違反、読み取り専用スコープ、越境学習利用の個別同意未保有など。
404Not Foundリソースが存在しません。未対応のモデル ID（単体照会）、存在しない呼び出し記録・ジョブ ID など。
409Conflict同じ Idempotency-Key のリクエストがすでに処理中。
413Payload Too Largeリクエスト本体が上限（デフォルト 50MB）を超過。
415Unsupported Media Type未対応の画像・マスク MIME 形式。
422Unprocessable Entityリクエストスキーマの検証失敗（フィールドの型・範囲違反など）。detail に位置と理由の配列が入ります。
429Too Many Requestsレート制限超過（キーごとにデフォルト 60 RPM）または全アップストリームが制限到達。Retry-After ヘッダーを尊重してください。
502Bad Gatewayアップストリームプロバイダーのエラー。テキストリクエストでは自動リトライとフォールバックを尽くした後も失敗した場合です。retryable フィールドでリトリーの意味を判断してください。
503Service Unavailable一時的に利用不可（カタログスナップショット検証不能・リミッター障害）。しばらくしてから再試行してください。

レスポンス形式#

エラー本体は 3 形式で返されます。多くは detail 内に文字列 またはオブジェクトを格納し、リクエストサイズ・形式系は OpenAI 互換の { error: { message, type } } 形式です。スキーマ検証失敗 （422）は detail に配列が入ります。

402 — 構造化エラー（課金・同意系）
{
  "detail": {
    "error": "insufficient_credits",
    "message": "사용 가능 크레딧 부족: 12,000 크레딧 < 54,000 크레딧. 대시보드 → 결제에서 충전해주세요.",
    "action": { "type": "topup", "path": "/billing" }
  }
}
502 — アップストリーム拒否（retryable + upstream 概要）
{
  "detail": {
    "error": "upstream_request_rejected",
    "message": "모델 제공자가 요청을 거부했습니다. 잠시 후 다시 시도하거나 다른 모델을 사용해주세요. (upstream 400: ...)",
    "retryable": false,
    "upstream": { "status": 400, "detail": "..." }
  }
}
413 — OpenAI 互換形式（本体サイズ）
{
  "error": {
    "message": "요청 본문이 너무 큽니다(최대 50MB).",
    "type": "payload_too_large"
  }
}
422 — スキーマ検証配列
{
  "detail": [
    {
      "loc": ["body", "duration_seconds"],
      "msg": "Input should be between 2 and 20",
      "type": "greater_than_equal"
    }
  ]
}

構造化エラーにはダッシュボードのパスを載せた action フィールドが含まれることがあり、状況に応じて retryable・providers・upstream が追加されます。message は常に韓国語です — 解析対象ではなく人間向けの案内と してください。

機械判読コード#

コード位置 · HTTP意味と解決
insufficient_creditsdetail.error · 402クレジット不足。ダッシュボード → 課金でチャージ後に再試行。
monthly_budget_exceededdetail.error · 402キーの月次予算超過。チャージではなくキー設定で予算を調整。
monthly_token_quota_exceededdetail.error · 402キーの月間トークン上限超過。キー設定で上限を調整。
org_member_monthly_budget_exceededdetail.error · 402チームメンバーの月次予算超過。チーム管理者に調整を依頼。
xborder_training_consent_requireddetail.error · 403学習利用プロバイダーの個別同意未保有。providers リストとともに返り、設定で同意すると解決。
org_membership_requireddetail.error · 403有効なチームメンバーシップが必要。
upstream_rate_limiteddetail.error · 429全アップストリームが制限到達。Retry-After 後に再試行。
upstream_unavailabledetail.error · 502アップストリームの一時障害（retryable=true）。しばらくしてから再試行。
upstream_request_rejecteddetail.error · 502アップストリームがリクエストを拒否（retryable=false）。リクエスト内容の確認またはモデル変更。upstream フィールドに概要を含みます。
catalog_snapshot_staledetail.error · 503カタログスナップショット検証不能。しばらくしてから再試行。
upstream_errorSSE error.codeストリーム途中でアップストリームが切断（SSE）。partial に受信済み内容が入り、その部分のみ課金。
invalid_requesterror.type · 400不正なリクエスト値（例：UUID を期待する箇所に非 UUID）。
payload_too_largeerror.type · 413リクエスト本体が上限を超過。
limiter_unavailableerror.type · 503リミッターの一時障害。しばらくしてから再試行。

ストリーミング中のエラー#

stream: true リクエストが途中で失敗しても HTTP ステータスは 200 のまま開いているため、失敗は最後の SSE イベントとして届きます。 partial オブジェクトにそれまでに受信した応答が入り、課金も その部分のみです。部分出力がない場合は data: [DONE] がすぐに 返ります。

SSE — stream failure
data: {"error": {"code": "upstream_error", "message": "모델 제공자 연결이 중단되었습니다. 받은 부분까지만 과금됩니다.", "partial": {...}}}

data: [DONE]

リトライガイド#

429 と 502（retryable=true） は指数バックオフでリトライしてください。テキスト経路はサーバーがプロバイダーごとに デフォルト 2 回の自動リトライ・フォールバックを行うため、クライアントのリトライ間隔は 1 秒以上を推奨します。4xx と retryable=false の 502 はリクエストを修正するまで同じ結果に なります。

メディア生成（画像・動画・音楽）にはサーバー側の自動リトライがありません（テキスト専 用）。retryable=true でも同一リクエストの即時リトライは同じ 結果になり得るため、先にパラメータを確認してください。

よくあるエラーと解決#

エラー解決
400 — 未対応のモデル ID（gpt-5.5-mini の入力ミスなど）メッセージに類似モデルの提案が含まれます。GET /v1/models で全リストを確認してください。
400/422 — メディアパラメータの拒否（duration・解像度・参照画像数など）モデル別の許容値は各メディアドキュメント（画像・動画）の制約表で確認してください。 エラーメッセージは拒否されたパラメータと許容値を示します。
402 — insufficient_creditsダッシュボード → 課金でチャージ後に再試行。予算・トークン上限コードの場合はキー設定で上限を調整します。
429 — レート制限Retry-After ヘッダーの値以降に指数バックオフで再試行してください。
502 — upstream_request_rejectedupstream の概要を確認してリクエストパラメータを点検し、 同じ結果が繰り返される場合は別のモデルへ切り替えてください。