大模型 API 常见报错(401 / 404 / 400 / 429)排障指南
90% 的接入报错来自三件事:Base URL 多写或漏写 /v1、把模型发到了不支持的端点(如对 DeepSeek 发 Responses),或给 Claude 5.x 原生接口传了非默认采样参数。
一分钟定位报错对照表
| HTTP 状态码 | 最常见原因 | 第一步怎么修 |
|---|---|---|
| 401 Unauthorized | Key 未导出、拼写有空格、或把 Bearer 头与 x-api-key 混错 |
核对环境变量 DEEPCLUB_API_KEY,确认在「API 令牌」页未过期或受限 |
| 404 Not Found | URL 拼出 /v1/v1/messages 或 /v1/v1/chat/completions,或模型 ID 写错 |
对照下表检查客户端是否会自动追加 /v1,模型 ID 与 实时目录 逐字符一致 |
| 400 Bad Request | 向 claude-opus-5-5/sonnet-5-5/fable-5-2 传了 temperature,或视频参数超规格 |
删除自定义 temperature/top_p/top_k;生图/视频先核对模型详情页规格 |
| 429 / 上游波动 | 客户端并发突发或上游瞬时限流 | 增加指数退避重试;检查子 Key 并发与账户余额是否充足 |
高频客户端 Base URL 正确写法(防 404 必查)
不同 SDK 和客户端对 /v1 的拼接规则不同,千万不要混用:
| 客户端 / SDK | 应填写的 Base URL / Host | 实际发出的请求路径 |
|---|---|---|
| Claude Code | https://deepclub.net(不带 /v1) |
/v1/messages |
| Anthropic Python/Node SDK | https://deepclub.net(不带 /v1) |
/v1/messages |
| Dify 官方 Anthropic 插件 | https://deepclub.net(不带 /v1) |
/v1/messages |
LangChain ChatAnthropic |
https://deepclub.net(不带 /v1) |
/v1/messages |
Vercel @ai-sdk/anthropic |
https://deepclub.net/v1(带 /v1) |
/v1/messages |
| Chatbox Claude Compatible | https://deepclub.net/v1 + Path /messages |
/v1/messages |
| OpenAI SDK / Cursor / Cline / Dify OpenAI | https://deepclub.net/v1(带 /v1) |
/v1/responses 或 /v1/chat/completions |
| 沉浸式翻译 | 完整 URL(如 https://deepclub.net/v1/chat/completions) |
按完整路径直发 |
为什么请求已经到了网关,模型却报错?
- 协议与模型不匹配:例如对
deepseek-v4.1-flash、gemini-4-hydrogen发送/v1/responses会报错,因为它们仅开放/v1/chat/completions;同理生图模型必须发往/v1/images/generations。 - Claude 5.x 原生接口采样参数限制:
claude-opus-5-5、claude-sonnet-5-5与claude-fable-5-2在原生/v1/messages不接受temperature=0或自定义top_p、top_k,请在框架或客户端中关闭温度覆盖。 - 打开使用日志核对:如果怀疑客户端实际发出的模型 ID 或协议被改写,直接登录深云 DeepClub 控制台「使用日志」,即可看到每笔请求最终落地的模型与状态。
常见问题
- 为什么我在 Dify 或 Claude Code 里填了 https://deepclub.net/v1 反而报 404?
- 因为 Claude Code 和 Dify 官方 Anthropic 插件都会自动在 Base URL 后面追加 /v1/messages。如果你多填了 /v1,最终地址会变成 /v1/v1/messages,从而返回 404。改成 https://deepclub.net 即可恢复。
- 提示模型不存在或无权访问,怎么确认正确的模型 ID?
- 请前往 /pricing 实时目录直接复制完整模型 ID(例如 claude-sonnet-5-5、gpt-6.1-sol、deepseek-v4.1-flash),不要沿用其他平台的厂商前缀(如 anthropic/ 或 openai/),并检查你的 API 令牌是否限制了可用模型列表。
- 报错 429 会扣费吗?怎么减少 429?
- 未成功处理的请求不会按正常响应计费,扣费明细以控制台使用日志为准。遇到突发并发限流时,建议在客户端设置合理并发上限并启用指数退避重试。
更新于