# エラー > エラーレスポンスの形式と主な HTTP ステータスコード。 Source: https://kiln.bricksum.com/docs/ja/errors エラーは標準の HTTP ステータスコードとともに返されます。ボディの形式はリクエストを拒否した層によって異なるため、message の文言ではなく HTTP ステータスと error.code で分岐してください。API が返すボディの形式は、以下に例とともにまとめています。 メモ 分岐はステータスコードと error.code で行い、message では行わないでください。message は人が読む文言で表現が変わることがあり、契約にあたるのはステータスコードと code です。 ## HTTP ステータス API が返すステータスを、対応方法ごとにまとめると次のとおりです。 - 400、404、405：リクエスト自体が不正です。修正してから送り直してください。 - 401、403：API キーを利用できません。キーを確認するか、新しく発行してください。 - 402：クレジット残高、組織の予算、キーの支出上限のいずれかがなくなっています。 - 429：レート制限を超過しました。リセット後にリトライするか、バックオフしてください。 - 500、502、503：Kiln 側の問題です。指数バックオフでリトライしてください。 ## ステータスコード ステータスコードはこの表を基準とし、他のページからもこの表を参照しています。クライアントでは以下のコードを明示的に処理してください。 | ステータス | error.code | 原因 | 対応 | | --- | --- | --- | --- | | 400 | empty_array, unsupported_parameter | 不正なリクエストです。不正な JSON、無効なパラメータ、モデルページに記載のモデル別コンテキスト長の超過、/v1/chat/completions の空または欠落した messages 配列、gpt-oss モデルでの ignore_eos、/v1/responses での previous_response_id が該当します。 | リクエストの内容を修正してください。同じ内容のままリトライしないでください。 | | 401 | - | 認証エラーです。API キーがない、形式が不正、未登録、または期限切れです。 | Authorization または x-api-key ヘッダー、キーの値、キーの有効期限を確認してください。 | | 402 | - | 支払いが必要です。クレジット残高がなくなった、組織が月間予算に達した、またはキーが支出上限に達した場合です。 | クレジットをチャージするか、管理者に予算またはキーの支出上限の引き上げを依頼してください。それまではリトライしないでください。 | | 403 | - | 権限がありません。API キーが一時停止中、または失効済みです。アーカイブされたプロジェクトのキーは一時停止として扱います。 | コンソールでキーを再有効化し、失効済みの場合は新しいキーを発行してください。 | | 404 | model_not_found, unknown_url, not_found | 見つかりません。モデルが存在しないか利用権限がない場合（model_not_found）、提供していないパスの場合（unknown_url）、保存済みレスポンスを取得しようとした場合（not_found、レスポンスは保持しません）です。 | モデル ID は GET /v1/models と、パスは API リファレンスと照合してください。 | | 405 | method_not_allowed | 許可されていないメソッドです。提供しているパスですが、この HTTP メソッドは受け付けません。 | レスポンスの Allow ヘッダーに記載されたメソッドを使用してください。 | | 429 | rate_limit_exceeded（同時実行のみ） | リクエスト過多です。組織単位の上限を超過しました。上限は、デフォルトで毎分 60 リクエスト、設定されている場合は毎分トークン数、または同時 8 リクエストです。 | 毎分リクエストまたは毎分トークンの 429 には x-ratelimit-reset が含まれるので、その秒数だけ待ってください。同時実行の 429 にはレート制限ヘッダーがないため、指数バックオフを使用してください。 | | 502 | - | ゲートウェイエラーです。上流のモデルバックエンドが失敗したか、到達できません。 | 指数バックオフでリトライし、長い生成にはストリーミングを使用してください。解消しない場合は運用チームにお問い合わせください。 | | 503 | - | サービスを利用できません。メンテナンスモード中か、利用可能なモデルバックエンドがありません。 | メンテナンス中はレスポンスに Retry-After ヘッダー（HTTP 日付）が含まれるので、その時刻まで待ってください。それ以外は指数バックオフでリトライしてください。 | | 5xx | - | サーバーエラーです。Kiln 側の一時的な問題です。 | 指数バックオフでリトライしてください。解消しない場合は運用チームにお問い合わせください。 | ## エラーボディの形式 - 認証、クレジット、RPM/TPM 上限による拒否（401、402、403、429）：{"error":{"message","type":"authorization"}} の形式です。code と param フィールドはありません。 - リクエスト検証と同時実行上限による拒否：error.type は invalid_request_error で、param と code が追加されます。code は model_not_found, empty_array, unsupported_parameter, rate_limit_exceeded, unknown_url, method_not_allowed, not_found のいずれかです。 - /v1/messages で認証後に返されるエラーは Anthropic 形式 {"type":"error","error":{"type","message"}} を使用します。 - GET /v1/key は {"error":{"message","code"}} を返し、type フィールドはありません。キーがない、未登録、一時停止中、期限切れの場合、code は unauthorized です。 - OpenAI 形式のエンドポイントの 502 と、利用可能なモデルバックエンドがないことによる 503 はボディがプレーンテキストのため、JSON としてパースしないでください。メンテナンス中の 503 は type が "maintenance" の JSON です。 **ゲートウェイによる拒否** ```json { "error": { "message": "missing or malformed API key", "type": "authorization" } } ``` **リクエスト検証** ```json { "error": { "message": "The model does not exist or you do not have access to it.", "type": "invalid_request_error", "param": "model", "code": "model_not_found" } } ``` **Anthropic 形式（/v1/messages）** ```json { "type": "error", "error": { "type": "invalid_request_error", "message": "max_tokens is required" } } ``` **GET /v1/key** ```json { "error": { "message": "invalid API key", "code": "unauthorized" } } ``` **プレーンテキスト（502、503）** ```http HTTP/1.1 502 Bad Gateway Content-Type: text/plain; charset=utf-8 upstream error ``` ## ストリーム開始前とストリーム途中の失敗 ### バイトが送られる前 拒否されたリクエストは、レスポンスのバイトが 1 つも送られる前に失敗します。クライアントは 2xx 以外のステータスと上記のいずれかのボディを受け取り、トークンは生成されず、課金もされません。上の表のすべての行がこの場合にあたります。 ### 200 のあと ゲートウェイが 200 と最初のストリームバイトを送ったあとは、HTTP ステータスを変更できません。モデルサーバーが生成の途中で失敗した場合は、ストリームが早く終わります。最後のチャンクと data: [DONE] の印がないまま終了するか、ストリームの中に error オブジェクトが届きます。このように失敗した生成は課金しません。 途中で切れたストリームは短い回答のように見えるため、次を確認してください。 - data: [DONE] がないまま終わったストリームは、ステータスが 200 でも失敗として扱ってください。 - 最後のチャンクに finish_reason があるか確認してください。finish_reason がないまま終わったストリームは完了していません。 - stream_options.include_usage を true に設定し、usage チャンクがない場合は失敗として扱ってください。 - レスポンスの X-Neocloud-Generation-Id ヘッダーをログに残し、失敗したリクエストをあとから追跡できるようにしてください。 429 の処理とリトライ戦略は、 [レート制限](https://kiln.bricksum.com/docs/ja/rate-limits) を参照してください。