错误排查

错误响应格式

出错时接口返回 JSON，错误信息在 error 字段里：

{
  "error": {
    "message": "No available channel for model gpt-5 under group default (distributor) (request id: 20260927155100934812128...)",
    "type": "new_api_error",
    "code": "model_not_found"
  }
}

字段	说明
`message`	具体原因，末尾的 `request id` 用于反馈问题时定位这次请求
`type`	`new_api_error` 表示由本站网关拦截；`upstream_error` 等表示来自上游模型服务
`code`	错误码，部分错误为空字符串，这时以状态码和 `message` 为准

使用 Anthropic 格式（/v1/messages）时，密钥、模型等校验错误同样是上面的格式；上游模型服务返回的错误可能按 Anthropic 格式返回。

对照表

400：请求内容有误

典型 `message` / `code`	原因	处理
`Model name not specified`	请求体里没有 `model` 字段	补上模型 ID
`invalid JSON request body`	请求体不是合法 JSON	检查引号、逗号、括号；用 JSON 工具校验
`field messages is required`（`invalid_request`）	缺少接口必填字段	对照创建对话补齐必填字段
其他参数相关报错	模型不支持某个参数或取值	先用最小请求跑通，再逐个加参数定位

401：密钥无效

典型 `message`	原因	处理
`Invalid token`	以下任意一种：密钥填错或不完整、没带密钥、密钥已删除、已禁用、已过期、密钥额度已用完	到控制台 API 密钥页面逐项检查：状态是否启用、有效期、剩余额度

401 不只代表”密钥填错”。密钥过期或额度用完也返回同样的 Invalid token。确认密钥没填错后，请到控制台检查它的状态、有效期和额度。

请求头格式为 Authorization: Bearer YOUR_API_KEY。Anthropic 格式接口也可以用 x-api-key: YOUR_API_KEY。

403：没有权限或余额不足

典型 `message` / `code`	原因	处理
`insufficient_user_quota`	账户余额不足	到余额与充值充值
`pre_consume_token_quota_failed`	密钥剩余额度不够这次请求预扣	提高密钥额度或改为无限额度
`该令牌无权访问模型 xxx`	密钥设置了可用模型范围，不包含这个模型	在密钥设置中加入该模型，或换用其他密钥
`该令牌无权访问任何模型`	密钥的可用模型范围为空	编辑密钥，重新选择可用模型
`您的 IP 不在令牌允许访问的列表中`（`access_denied`）	密钥设置了 IP 白名单	把当前出口 IP 加入白名单，或清空白名单
`无权访问 xxx 分组` / `分组 xxx 已被弃用`	密钥所选分组不可用	编辑密钥，换一个可用分组

404：地址错误

典型 `message`	原因	处理
`Invalid URL (POST /v1/v1/chat/completions)`	地址重复拼了 `/v1`	SDK 的 Base URL 填 `https://token.poryf.com/v1`，不要再手动加 `/v1`
`Invalid URL (POST /chat/completions)`	地址漏写了 `/v1`	SDK 的 Base URL 改为 `https://token.poryf.com/v1`
`Invalid URL (POST /v1)`	工具要求填完整接口地址，却只填了 Base URL	改为 `https://token.poryf.com/v1/chat/completions`

429：请求太频繁

典型 `message`	原因	处理
`您已达到请求数限制：N 分钟内最多请求 M 次`	触发本站的请求频率限制	降低并发，等待后重试
`您已达到总请求数限制……包括失败次数`	失败请求也计入次数，通常是程序在反复重试一个错误请求	先修正请求本身，不要无限重试
来自上游的限流提示	上游模型服务繁忙	指数退避重试，或换同系列的其他模型

5xx：服务端或上游异常

状态码 / `code`	原因	处理
503 `model_not_found`	模型 ID 不存在，或当前没有可用线路。模型 ID 末尾多了空格也会报这个错	从模型列表复制精确 ID；ID 确认无误仍报错时稍后重试
500 `convert_request_failed`	该模型不支持当前使用的接口格式	换用该模型支持的接口，例如改用 `/v1/chat/completions`
500 / 502 / 504 `do_request_failed`、`bad_response_status_code` 等	上游模型服务异常或超时	稍后重试；持续出现请带 `request id` 反馈

不报错但结果异常

现象	原因	处理
返回 200 但 `content` 为空，`finish_reason` 为 `length`	推理模型先输出思考过程，`max_tokens` 太小时额度被思考用完，正文还没开始	调大 `max_tokens`，或读取 `reasoning_content` 查看思考内容

工具里显示的报错

编程工具有时会把服务端错误换成自己的提示语：

工具	提示	实际含义
Codex	`We're currently experiencing high demand`	服务端返回了 500，常见原因是所选模型不支持 Responses 接口，见 Codex 教程

遇到看不懂的提示时，可以在使用日志里找到这次请求，查看原始错误。

该不该重试

状态码	是否重试
400、401、403、404	不要重试，先修正请求、密钥或配置。重复发送同一个错误请求还可能触发 429
429	可以重试，降低并发，按 1 秒、2 秒、4 秒逐步延长间隔
5xx	可以有限次重试（建议不超过 3 次）；持续失败请反馈

每次成功的请求都会单独计费。程序自动重试时请设置上限，避免请求其实已成功却被重复发送。

反馈问题

请提供发生时间、模型 ID、接口路径、错误正文中的 request id，以及脱敏后的错误信息。不要发送完整密钥、Authorization 请求头或包含个人信息的对话内容。

概览

接入指南

文本系列

图像系列

视频系列

语音系列

素材库

使用与计费

常见问题

错误响应格式

对照表

400：请求内容有误

401：密钥无效

403：没有权限或余额不足

404：地址错误

429：请求太频繁

5xx：服务端或上游异常

不报错但结果异常

工具里显示的报错

该不该重试

反馈问题

​错误响应格式

​对照表

​400：请求内容有误

​401：密钥无效

​403：没有权限或余额不足

​404：地址错误

​429：请求太频繁

​5xx：服务端或上游异常

​不报错但结果异常

​工具里显示的报错

​该不该重试

​反馈问题

错误响应格式

对照表

400：请求内容有误

401：密钥无效

403：没有权限或余额不足

404：地址错误

429：请求太频繁

5xx：服务端或上游异常

不报错但结果异常

工具里显示的报错

该不该重试

反馈问题