> 面向 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` |
| 请求体大小 | 16 MiB | `413` |
| 输出长度 | [按模型——见下表](https://gate.joingonka.ai/zh/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 秒 | `429 queue_timeout` 并带 `Retry-After: 1` 请求头 |
| 网络开始响应，流式 | 150 秒 | `504 upstream_timeout`；会按输入 token 估算扣费 |
| 网络开始响应，非流式 | 150 秒 | `504 upstream_timeout`；会按输入 token 估算扣费 |
| 生成响应 | ≈ 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` 时，会扣除输入 token 的预估费用，输出不扣；重试会再次扣费。在最终 `usage` 之前中断的流，计费方式相同。长回复请使用 `stream: true`。

## 错误码

错误正文是一个 `error` 对象，包含 `message, type, code, param`；并非所有错误都有全部字段。请以状态码和 `type` 为准，并通过 `code` 确认细节：`message` 文本可能会变化。Anthropic 格式见 [Anthropic 错误格式](https://gate.joingonka.ai/zh/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` | 已超出每个密钥每分钟的请求数限制；正文中包含 `rate_limit` 和 `limit, remaining, reset` | 等待 `Retry-After` 中指定的秒数 |
| 429 `rate_limit_exceeded` `upstream_rate_limited` | Gonka 网络上的模型过载 | 在 `Retry-After` 后重试，或换用其他模型 — [模型](https://gate.joingonka.ai/zh/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` | 网络提供商拒绝了网关的凭据 — 你的密钥没有问题 | 一分钟后重试 |
| 502 `api_error` | Gonka 网络错误；如果网络发送了 `code`，则来自网络 | 暂停后重试，或换用其他模型 |
| 503 `model_unavailable` `model_outage` `model_initializing` `model_unstable` `model_not_served` | 根据网络探测，该模型当前不可用：崩溃、启动中、不稳定，或无人提供服务；会立即拒绝，无需等待 | 换用其他模型 — 错误文本会提示用哪个；列表见 [模型](https://gate.joingonka.ai/zh/docs/models) |
| 503 `service_unavailable` | 没有可用节点 | 稍后重试 |
| 504 `timeout` `upstream_timeout` | 网络已接受请求，但未及时响应；输入 token 的预估费用已扣除 | 长回复请使用 `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`。