エラー

エラーは標準の 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 です。

ゲートウェイによる拒否

{
  "error": {
    "message": "missing or malformed API key",
    "type": "authorization"
  }
}

リクエスト検証

{
  "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）

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens is required"
  }
}

GET /v1/key

{
  "error": {
    "message": "invalid API key",
    "code": "unauthorized"
  }
}

プレーンテキスト（502、503）

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 の処理とリトライ戦略は、レート制限を参照してください。