18. エラーコードとエラー処理#
エラー発生時は OpenAI 互換のエラー構造を返します（/v1/messages エンドポイントは Anthropic 形式のエラー構造を返します）：
JSON
{
"error": {
"message": "错误描述",
"type": "invalid_request_error",
"code": 400
}
}
一般的なステータスコード#
| ステータスコード | 意味 | 切り分けのヒント |
|---|---|---|
400 | リクエストパラメータの欠落または不正 | model、messages、input などの必須フィールドを確認してください。/v1/messages には tools / マルチモーダルを送らないでください |
401 | API キーがない、または無効 | Authorization: Bearer sk-... が正しいこと、キーが期限切れ / 失効していないことを確認してください |
402 | クォータ消費済みまたは残高不足 | コンソールでチャージするか、キーのクォータを調整してください |
403 | 送信元 IP がホワイトリストにない | キーの IP ホワイトリスト設定を確認してください |
404 | モデルが存在しない / アクセス権がない、またはタスクが存在しない | GET /v1/models で利用可能なモデルを確認してください。パスの /v1 が 1 つだけであることも確認してください |
429 | レート制限に抵触 | 同時実行を下げ、指数バックオフ後に再試行してください |
500 | ゲートウェイ内部エラー | 時間をおいて再試行してください。解消しない場合はサポートにお問い合わせください |
502 | 上流ベンダーが異常応答を返しました | 時間をおいて再試行するか、モデルを変更してください |
503 | 利用可能なチャネルがない | このモデルに利用可能な上流が現在ありません。時間をおいて再試行するか、サポートにお問い合わせください |
エラー処理のヒント#
429、5xxは自動再試行を行ってください（指数バックオフ + 最大再試行回数）。400、401、403などのクライアントエラーは再試行しないでください。リクエストを修正してください。- トラブルシューティング時にサポートチームへ提供できるよう、レスポンス中の
X-Request-Id（存在する場合）を記録してください。