报错与踩坑

• 参数名拼写错误（如 max_token 应为 max_tokens）
• 参数类型错误（如传字符串给 temperature）
• 必填参数缺失（如 model、messages）
• 参数值超出范围（如 temperature: 5）
• 枚举值错误（如 tool_choice: "always" 应为 auto / none / required）

1. 仔细阅读 error.message，通常会指出哪个参数有问题
2. 对照 Chat Completions 参数表 或 Messages 参数表
3. 用 json.loads() 在客户端打印请求体，确认序列化正确
4. 用 curl 重试，排除 SDK 封装问题

输入 prompt 的 token 数超过模型的最大上下文窗口。

1. 精简 prompt：删除冗余历史、压缩上下文
2. 分块处理：长文档分多次输入
3. 换模型：用长上下文模型（如 Claude Sonnet 5 1M、GPT-5.6 Terra 1.05M）
4. 使用 Prompt 缓存：Anthropic 支持，可降低重复输入成本

• Key 字符串复制时多了空格 / 少了字符
• Key 已被禁用（在控制台「接口密钥」页面停用了）
• Key 已删除
• 鉴权头格式错误（Authorization: <API Key> 漏了 Bearer 前缀）
• 协议不匹配：使用的 API Key 与请求协议不匹配（请以控制台为该 Key 提供的协议配置为准）

1. 打印实际的鉴权 Header，确认完整且格式正确
2. 在控制台「接口密钥」页面确认 Key 状态为「启用」
3. 测试时临时新建一个 Key，排除污染因素
4. 按 SuperRoute 控制台为该 Key 提供的协议配置客户端，不要根据 Key 的固定前缀判断协议

1. 立即充值（superoute.uk/billing）
2. 充值后无需等待，秒级恢复

Key 已被管理员或用户主动禁用。

1. 在控制台「接口密钥」重新启用该 Key
2. 如 Key 已泄露，立即创建新 Key 并禁用旧 Key

Key 绑定的协议与请求协议不匹配。请使用 SuperRoute 控制台为该 Key 提供的协议配置客户端；Key 的具体字符串格式（例如 sk_test_822f61571c0a4c608e88af5985ddd7fa）不能单独用来判断协议。

• 对应 OpenAI 兼容协议时调用 /v1/chat/completions
• 对应 Anthropic 协议时调用 /v1/messages

使用与请求协议匹配的配置。API Key 请从 SuperRoute 控制台生成并以平台实际分配的协议为准。

当前 Key 绑定的档位不支持该模型。 例如：某些限量模型可能只对 🚀 full 档位开放。

查看 [模型列表](/docs/models)，确认该模型在你当前档位下可用。 如需使用，创建一个绑定到合适档位的 Key。

• 模型名拼写错误（如 gpt-5-5-luna 应为 gpt-5-6-luna）
• 模型名大小写错误（一般不敏感，但建议统一用官方小写）
• 模型已下线（查看 [更新日志](/docs/new-document)）

对照 [模型列表](/docs/models) 修正模型名。

请求体超过了单次请求的体积限制（默认 20MB）。 通常由 base64 编码的大图片或大批量消息引起。

1. 图片：压缩后再上传，或使用 URL 引用
2. 消息：分批发送，或先做总结压缩
3. 联系商务提升单请求体积限制

触发了限速。响应头会包含限速信息：

X-RateLimit-Limit-Requests: 500
X-RateLimit-Remaining-Requests: 0
X-RateLimit-Reset-Requests: 23s

1. 实现指数退避：

   import time, random
   for attempt in range(5):
       try:
           resp = client.chat.completions.create(...)
           break
       except RateLimitError:
           wait = (2 ** attempt) + random.random()
           time.sleep(wait)
   

2. 降低并发：使用 semaphore 控制并发数
3. 升级档位：fast / full 档位的限速更高
4. 多 Key 分流：创建多个 Key 轮询使用

SuperRoute 平台内部错误。 会自动重试 1 次（仅 stable / full 档位）。

1. 客户端实现重试（fast 档不会自动重试）
2. 持续失败请提工单，附上请求 ID（从响应头 X-Request-Id 获取）

上游模型服务方出现故障。 会自动重试 1 次（仅 stable / full 档位）。

1. 等几分钟重试
2. 加入 QQ 群（见文档底部）查看最新故障通知
3. 客户端实现退避重试

上游过载。会自动重试。

1. 客户端实现指数退避
2. 错峰使用
3. 如长期过载，可考虑降级到 fast 档（fast 档走不同通道池）