错误码速查

请求失败时，先看 HTTP 状态码，再看响应体中的 error.message、error.type、error.code 和请求日志。

常见状态码

状态码	含义	处理方式
400	请求参数错误	检查 JSON 格式、字段名、模型参数
401	鉴权失败	检查 API Key 和 Header
403	权限不足	检查模型权限、Key 状态、账号状态
404	地址或模型不存在	检查 Base URL、路径、模型 ID
405	请求方法错误	确认接口使用 POST 或 GET
408	请求超时	降低上下文、增加客户端超时
413	请求体过大	减少输入内容或分批处理
429	频率或额度限制	降低并发，检查额度
500	平台或上游内部错误	稍后重试，记录请求 ID
502	上游不可用	重试或切换模型
503	服务繁忙	降低请求速度或稍后重试
504	上游超时	减少上下文，增加超时，拆分任务

401 鉴权失败

检查项：

• Header 是否符合协议要求。
• Key 是否完整复制。
• Key 是否已被删除、停用或过期。
• 环境变量是否被当前进程读取。

OpenAI 兼容：

Authorization: Bearer sk-your-dinghui-key

Anthropic 兼容：

x-api-key: sk-your-dinghui-key
anthropic-version: 2023-06-01

404 模型或地址不存在

常见原因：

• Base URL 写成了 https://www.tophdd.cn/v1/v1。
• 工具需要 /v1，但只填了主域名。
• 模型 ID 写错。
• 模型展示名被当成模型 ID。

429 频率限制

处理建议：

1. 降低并发。
2. 增加退避重试。
3. 减少单次任务的自动循环。
4. 检查 Key 的额度和限制。
5. 对批量任务做队列化处理。

5xx 上游异常

5xx 通常不是请求格式问题。建议：

• 记录请求时间、模型、请求 ID。
• 进行有限次数重试。
• 切换备用模型或备用策略。
• 对生产业务设置降级文案。

排查顺序

1. 看控制台是否有请求日志。
2. 有日志时，看模型、状态码、错误信息。
3. 无日志时，检查 Base URL、网络和客户端配置。
4. 用最小 curl 请求复现。
5. 再回到具体工具中修改配置。