文档 · 排查问题

常见错误响应

2026-11-12

网关返回的每个状态码和错误码是什么意思，重试前该改什么。

不管后面是哪家供应商，网关返回的错误都是同一个格式。OpenAI 风格的端点返回 {"error":{"message":"...","type":"...","code":"...","param":null}}，/v1/messages 返回 {"type":"error","error":{"type":"...","message":"..."}}。message 末尾带 (request id: ...)，响应头 x-request-id 里是同一个 id。流式响应已经开始的话，状态码早就是 200 了，错误会变成一条 data: {"error":...} 事件发过来（/v1/messages 上前面多一行 event: error），然后流直接结束，没有 [DONE]。/v1/responses 的流一旦开始，不管是中途断开还是供应商报错，最后一条都是 response.failed（见最后两节）。找客服时把这个 id 一起发过来：提示词和回复都不落盘，能查的只有这个 id。

401 authentication_error

没带 key 时，消息是「你没有携带密钥」。其余情况的消息是「密钥错误或已失效」。两条都附带处理地址，语言跟随 Accept-Language，英文分别是 You did not send an API key 和 This API key is wrong or no longer valid。原因只有几种：没带 key、放错了请求头、key 已停用或过期、key 自己的 额度（USD）（英文界面 Quota (USD)）已经花到零。额度还剩一点、但不够这次请求预估费用的，报 402 而不是 401。401 说的永远是你的 key，不会是我们和上游之间的凭证；上游凭证出问题会报成 upstream_unavailable。key 放在 Authorization: Bearer sk-... 里发。

base URL 还以 https://ai.topxea.com 开头的，把这一段换成 https://api.topxai.xyz，例如 https://api.topxai.xyz/v1。旧地址会跳转过来，但客户端跟着跳到另一个域名时会丢掉 key，请求到这边就成了没带 key，返回「你没有携带密钥」，消息里写着新旧两个地址。TopxAI Desktop 1.56 及更早的版本没有改地址的设置项，请到下载页下载新版，拖进「应用程序」替换旧版，打开后重新登录一次。聊天记录、项目和设置都会保留。

403 permission_denied

看 message 就知道卡在哪一道检查：

Model is not offered by this service：模型 id 不存在，或者大小写写错了。id 要一字不差，是 GLM-5.3-Abliterated，不是 glm-5.3-abliterated。
Model is not available on this API key route：这把 key 的分组（Group）不卖这个模型。新建一把选 自动路由（Auto route）的 key。
This token has no access to model ...：key 的 模型限制（Model limits）把这个模型排除了。
The service is not available in your region. 或 Your service region could not be verified. Please contact support.：地区访问限制。这条响应的 code 是 region_unavailable，没有 request id。
Requests from this account to models from this provider are paused until 2026-10-17 09:20 UTC because the provider rejected a request from this account for its content. Contact support if this is a mistake.：Claude、GPT、Grok 以及图片和视频模型（还有 Kimi K3.1 Pro 和 Jev 的备用线路）背后的供应商以内容为由拒绝了这个账号的一个请求，网关因此在接下来 24 小时里拒绝这个账号调用这些模型，其他模型照常可用。判断有误的话，请发邮件到 support@topxai.xyz。

402 insufficient_quota

消息是 Insufficient quota. Top up your balance and try again.。请求转发之前，网关会先按「提示词 + 允许的输出长度」估一笔费用（输出按 max_tokens、max_completion_tokens 或 max_output_tokens 算，没设就按 8192 个 token），从余额和 key 的额度里预留，请求结束后再按实际用量结算。余额明明大于零却收到 402，说明预留的金额超过了余额或 key 的额度：调低 max_tokens，调高 key 的额度，或者去钱包（Wallet）页用 充值余额（Add credit）充值。

429 rate_limited

来源有两个。一是网关按账户设的限流，同一账户下所有 key 合并计数：您已达到请求数限制：N分钟内最多请求M次 只记成功请求，您已达到总请求数限制：N分钟内最多请求M次，包括失败次数，请检查您的请求是否正确 连失败请求一起记。消息的语言跟着请求头 Accept-Language 走（中、英、日、俄、西）；没带这个头时用账户里保存的语言，账户没保存过才是英文。二是供应商那边的限流，返回 Rate limit exceeded. Please retry after a short delay.。两种情况下，只要响应里有 Retry-After 头，就按头里的秒数等。

400 invalid_request

供应商拒绝的请求，统一返回 The request was rejected. Check the parameters and try again.，供应商原话不透传。网关自己做的校验会保留原消息，比如 duration must be between 1 and 15 seconds。触发安全策略的请求返回 content_filtered，网关不会换渠道重试。转发给 Claude、GPT、Grok 以及图片和视频模型（或 Kimi K3.1 Pro 和 Jev 的备用线路）之前，网关还会检查请求里有没有越狱用语和指向违禁内容的词。命中时同样返回 content_filtered，消息里写明是哪个词：The request contains a term that is not allowed for this model: "<term>". Remove it and try again.。这样的请求不会发给供应商，也不扣费。走 /v1/chat/completions 和 /v1/messages 时，GLM-5.3-Abliterated 不会因为带图报错：网关会把每个附件换成一句 [Attachment omitted: this model accepts text only.]，文字部分照常转发。

404 和 5xx

上游返回 404 时是 model_not_found，internal_error 是 500。upstream_unavailable 是 502；供应商报过载，或者当下没有渠道能服务这个模型，都是 503。upstream_timeout 是 504。能换渠道重试的，网关已经试过了。失败的请求会退款，预留的金额直接回到余额；流已经生成了输出、之后才断开或报错的，按这部分输出收费（见下文）。账单退款（Billing refunds）那一栏不记这类退回，只记后来的更正。视频是例外：供应商接单那一刻就扣费，查询任务状态时，失败或过期的任务全额退款，比要求短的视频按比例退，这类退款会出现在账单退款里。

配置了备用的文本线路，默认连续三次上游故障后，新请求改走备用。当前请求尚未输出时，可以立即重试备用；主线恢复后自动回切。恢复检查和例外情况见自动切换说明。

stream_interrupted

供应商的流在回答写完之前断了，或者长时间没有新数据。已经到达的内容照常发给你，但结尾不是正常的 [DONE]、message_stop 或 response.completed，而是一条错误：OpenAI 风格的端点上 code 是 stream_interrupted，type 是 upstream_error；/v1/messages 上 type 是 api_error。/v1/responses 的流以 response.failed 结束，error.code 是 server_error，消息相同。OpenAI 和 Anthropic 的 SDK 收到这条事件会抛异常。手上的文字不完整，重新发一次请求。如果断开时一个字节都还没发给你，网关会先换一次尝试，仍然失败就返回 HTTP 502 和这个 code。供应商已经写完回答、之后连接才断的，按正常结束处理。

断开前生成的输出只收一次费：供应商报了用量就按它报的算，没报就按网关数出的文字算。一点输出都没有的流全额退款，记为失败请求；在第一个 token 出来之前取消的请求也一样。回答写到一半时取消，已经生成的部分照常收费。

回答写到一半时报错

供应商在回答写到一半时报错，已经到达的文字照常发给你，接着是一条错误事件，格式同上，code 和平时这类错误一样（比如 upstream_unavailable），结尾没有正常的结束标记。/v1/responses 的流以 response.failed 结束，error.code 是 server_error，消息相同；还没收到文字就报错的也一样。手上的回答不完整，重新发一次请求。

计费和流中途断开一样：报错前生成的输出只收一次费；一点输出都没有就报错的，全额退款，记为失败请求。重试不会再收第二次。只有一个例外：Grok 的儿童安全检查拒掉的请求，即使回答已经写了一半，也是先退预留，再单独扣违规费。