> AI エージェント向け：セットアップの手順ガイド — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md)、ドキュメントのインデックス — [`/llms.txt`](https://gate.joingonka.ai/llms.txt)。

# エラーと制限

ゲートウェイのレート制限、タイムアウト、エラーコード。各レスポンスについて、それが発生する条件と対処法（リクエストの再試行または修正）を説明します。

## 制限

数値はレスポンス`GET /v1/capabilities`の`limits`フィールドにあります。常に最新の値が記載されています。

| 制限 | 値 | 超過時 |
| --- | --- | --- |
| キーあたりの毎分リクエスト数 | 120、最初のリクエストからの60秒ウィンドウ | `429 rate_limit_exceeded`とヘッダー`Retry-After`。ゲートウェイの5xx拒否はクォータを消費しません |
| アカウントの同時リクエスト数 | 制限あり | 超過分はキューで待機。待ちきれない場合は`429 queue_timeout` |
| リクエストボディのサイズ | 16MiB | `413` |
| 出力の長さ | [モデル別 — 下の表を参照](https://gate.joingonka.ai/ja/docs/errors#max-tokens) | モデルの上限を超えた場合、エラーなしで上限まで切り捨て |
| 子キー | 管理キーあたり最大50個、各120リクエスト/分 | 上限の引き上げはサポート経由で |

### モデル別の出力の長さ

`max_tokens`を指定しない場合、ゲートウェイはデフォルト値を適用します。非ストリーミングではタイムアウトに収まるよう短めに、ストリーミングではモデルの上限に。`max_completion_tokens`は同じフィールドです。

| `model` | 上限 | 非ストリーミング | ストリーミング |
| --- | ---: | ---: | ---: |
| `MiniMaxAI/MiniMax-M2.7` | 8192 | 1500 | 8192 |
| `deepseek-ai/DeepSeek-V4-Flash-0731` | 32768 | 1500 | 32768 |
| `zai-org/GLM-5.3-Flash` | 8192 | 3000 | 8192 |

## タイムアウト

| 段階 | 値 | 発生する内容 |
| --- | --- | --- |
| キューの順番待ち | 45秒 | `Retry-After: 1`ヘッダー付きの`429 queue_timeout` |
| ネットワーク応答の開始、ストリーミング | 150秒 | `504 upstream_timeout`。入力トークンの推定値が請求されます |
| ネットワーク応答の開始、非ストリーミング | 150秒 | `504 upstream_timeout`。入力トークンの推定値が請求されます |
| 回答の生成 | ≈300秒 | ネットワークが生成を中断：レスポンスは`finish_reason: length`付きで返ります。次のリクエストで続けてください |
| ストリームのチャンク間のポーズ | 30秒 | ストリームが閉じます：チャンク`joingonka-stream-stalled`の`finish_reason: stop` |
| ストリームのキープアライブシグナル | 15秒 | コメント`: keep-alive` — SSEクライアントはこれをスキップします |
| ストリームの開始 | 30秒 | この時点まではレスポンスコードで拒否が返り、それ以降はチャンク`joingonka-error`で返ります |
| 非ストリーミングの早期レスポンス | 90秒 | ゲートウェイは`200`を返し、15秒ごとにスペースを送信します — JSONは有効なままです。その後のエラーは`error`フィールドを含むボディで返り、ステータスは`200`のままです |

> **タイムアウト時の請求内容**
>
> ネットワークが受理したリクエストはキャンセルできません。`504 upstream_timeout` の場合、入力トークンの見積もり分が課金され、出力分は課金されません。再試行は新たな課金となります。最終的な `usage` の前に途切れたストリームも同様に課金されます。長い応答が必要な場合は `stream: true` をご利用ください。

## エラーコード

エラー本体は `message, type, code, param` フィールドを持つ `error` オブジェクトです。すべてのエラーに全フィールドがあるわけではありません。ステータスと `type` を基準にし、`code` で詳細を確認してください。`message` のテキストは変更される可能性があります。Anthropic 形式については [Anthropic エラー形式](https://gate.joingonka.ai/ja/docs/errors#anthropic-errors) のセクションをご覧ください。

```json
{
  "error": {
    "message": "Model is currently overloaded in the Gonka network",
    "type": "rate_limit_exceeded",
    "code": "upstream_rate_limited"
  }
}
```

| レスポンス | タイミング | 対処方法 |
| --- | --- | --- |
| 400 `invalid_request_error` | 不正なリクエストボディ: `messages` がない、メッセージがオブジェクトでない、ボディが JSON でない。未知のモデルの場合は `param` とともに `model`、および利用可能なモデル一覧がテキストに含まれます | エラーメッセージに従ってリクエストを修正してください |
| 400 `invalid_request_error` `empty_content_after_normalization` | 正規化後にメッセージが空 — 例えば画像のみが含まれていた場合 | メッセージにテキストを追加してください |
| 400 `invalid_request_error` `web_search_privacy_sanitization_not_supported` | 同一リクエスト内に `web` と `privacy-sanitization` のプラグインが共存 | どちらか一方のみを使用してください |
| 400 `invalid_request_error` `previous_response_id_not_supported` `conversation_not_supported` `item_reference_not_supported` `background_not_supported` `hosted_tool_choice_not_supported` | OpenAI Responses: 保存された応答・会話・アイテムへの参照、バックグラウンドモード、組み込みツールの要求 | 履歴全体を `input` に含めて送信してください |
| 400 `api_error` | ネットワークがパラメータを拒否 — 例えば `reasoning_effort` の値がネットワークのリストにない場合 | エラーメッセージに従って値を修正してください |
| 401 `authentication_error` | キーが見つからない、取り消されている、または不明な形式 | [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys) ページでキーを確認してください |
| 402 `insufficient_funds` | リクエストの見積もりに対して残高が不足しています。残高は `balance_ngonka` にあります | 残高をチャージしてください: [gate.joingonka.ai/billing](https://gate.joingonka.ai/billing) |
| 402 `insufficient_funds` | サイト以外からのキーなしリクエスト (`is_demo: true`) | API キーを送信してください |
| 402 `child_key_limit_exceeded` | キーの支出上限を超過 — 日次、月次、または累計。残量は `daily_remaining, monthly_remaining, total_remaining` にあります | [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys) ページでキーの上限を引き上げるか、リセットを待ってください |
| 403 `forbidden` | モデルへのリクエストに管理キー `gm-` を使用。アカウント専用ルートに API キーを使用 | リクエストには `jg-` または `gc-` キーを使用してください。アカウント管理はダッシュボードで行ってください |
| 404 `invalid_request_error` `model_not_found` | `GET /v1/models/{model}`: モデルがカタログに存在しないか、一時的に非表示になっています | `GET /v1/models` から id を取得してください |
| 404 `invalid_request_error` `not_found` `compact_not_supported` | OpenAI Responses: `/v1/responses/{id}` およびその他のステートフルアドレス、`/v1/responses/compact` | 履歴はご自身で保持してください。Codex CLI の場合はプロバイダー ID を独自に設定してください |
| 404 `invalid_request_error` | 不明なパス | メソッド、パス、ベースアドレスを確認してください |
| 413 `invalid_request_error` | リクエストボディが上限を超過 | リクエストを縮小してください |
| 415 `invalid_request_error` | ヘッダーによるとボディが JSON でない: `Content-Type: application/json` が必要です | `Content-Type: application/json` を送信してください |
| 429 `rate_limit_exceeded` | キーあたりの 1 分間のリクエスト数が上限を超過。ボディに `limit, remaining, reset` を含む `rate_limit` があります | `Retry-After` に示された秒数だけ待ってください |
| 429 `rate_limit_exceeded` `upstream_rate_limited` | Gonka ネットワーク上でモデルが過負荷状態です | `Retry-After` 後に再試行するか、別のモデルを使用してください — [モデル](https://gate.joingonka.ai/ja/docs/models) |
| 429 `rate_limit_exceeded` `queue_timeout` `queue_full` | ネットワークの全スロットが使用中: キューが満杯か、待機時間が超過しました | `Retry-After` 後に再試行してください |
| 500 `server_error` | ゲートウェイの内部エラー | 後で再試行してください。繰り返す場合は、`x-request-id` を添えてサポートにお問い合わせください |
| 501 `not_implemented` | `POST /v1/embeddings`: ネットワークに埋め込みモデルがありません | 別の埋め込みサービスをご利用ください |
| 502 `api_error` `upstream_unauthorized` | ネットワークプロバイダーがゲートウェイの認証情報を拒否 — お客様のキーは正常です | 1 分後に再試行してください |
| 502 `api_error` | Gonka ネットワークのエラー。`code` はネットワークから送信された場合のネットワーク側の情報です | 間隔を空けて再試行するか、別のモデルを使用してください |
| 503 `model_unavailable` `model_outage` `model_initializing` `model_unstable` `model_not_served` | ネットワークのプローブによりモデルが現在利用不可: 障害、起動中、不安定、または誰もサービスを提供していない状態。待機せず即座に拒否されます | 別のモデルを使用してください — エラーメッセージがどのモデルかを示します。一覧は [モデル](https://gate.joingonka.ai/ja/docs/models) |
| 503 `service_unavailable` | 利用可能なノードがありません | 後で再試行してください |
| 504 `timeout` `upstream_timeout` | ネットワークがリクエストを受理しましたが、時間内に応答しませんでした。入力トークンの見積もり分は課金されました | 長い応答には `stream: true` をご利用ください。再試行は新たな課金となります |

## オープンストリーム内のエラー

ストリームが開かれる前は、拒否は通常のレスポンスコードで返されます — 非ストリーミング時と同じです。開いた後はステータスが既に `200` となり、エラーは次のように返されます:

- Chat Completions — `error` フィールドを持つ `joingonka-error` チャンク、その後 `[DONE]` なしで切断されます。
- 早期応答後の非ストリーミング — ステータス `200` と `error` フィールドを持つボディ。
- Anthropic Messages — `event: error` イベント、その後ストリームが閉じられます。
- OpenAI Responses — `response.failed` イベント、原因は `response.error.code` にあります。
- Legacy Completions — `data: {"error": …}`、その後 `[DONE]`。

```text
data: {"id":"joingonka-error","object":"chat.completion.chunk","model":"MiniMaxAI/MiniMax-M2.7","choices":[],"error":{"message":"Gonka network error","type":"api_error"}}
```

## Anthropic エラー形式

- `POST /v1/messages` は Anthropic エンベロープで応答します: `{"type": "error", "error": {"type", "message"}}`。
- ゲートウェイの拒否は上記の表の `type` を保持します (`insufficient_funds`、`model_unavailable` など)。このエンベロープには `code` フィールドはなく、原因はテキストに記載されています。
- リクエスト形式のエラー — `invalid_request_error`: メッセージまたは `max_tokens` がない、名前のないツール呼び出し、未知のモデル。
- 不明なパス — `not_found_error`、ボディが大きすぎる — `request_too_large`。

```text
event: error
data: {"type":"error","error":{"type":"timeout","message":"Upstream timeout"}}
```

## 再試行すべきケース

- `Retry-After` に示された待機後: `429`
- 指数的バックオフ — 1、2、4 秒以降: `500`, `502`, `503 service_unavailable`, `504`
- 別のモデルで: `503 model_unavailable`
- 変更なしで再試行しない — リクエスト、キー、または残高を修正してください: `400`, `401`, `402`, `403`, `404`, `413`, `415`, `501`

`504` 後の各再試行は入力見積もりの新たな課金となります。長い応答には `stream: true` を有効にしてください。

エラーが繰り返す場合は、レスポンスヘッダーの `x-request-id` を添えてサポートにお問い合わせください。