面向 AI 智能体：配置分步指南 — /docs/agents.md，文档索引 — /llms.txt。

错误与限制

网关的请求限制、超时和错误码。每个响应都会说明其触发条件以及应对方式：重试请求还是修正请求。

这些数值来自 GET /v1/capabilities 响应的 limits 字段：那里的值始终是最新的。

各模型的输出长度#

未传 max_tokens 时，网关会套用默认值：非流式时取较小值，以便响应在超时前完成；流式时用模型上限。max_completion_tokens 是同一个字段。

错误正文是一个 error 对象，包含 message, type, code, param；并非所有错误都有全部字段。请以状态码和 type 为准，并通过 code 确认细节：message 文本可能会变化。Anthropic 格式见 Anthropic 错误格式 部分。

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

在流打开之前，拒绝会以普通响应码返回 — 与不使用流式传输时相同。打开之后，状态码已经是 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]。

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

• 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。

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。