错误码
错误响应结构
所有错误都长这个样：
json
{
"error": {
"message": "Invalid token",
"type": "new_api_error",
"param": "",
"code": "invalid_token"
}
}message 是给人看的，code 是给程序判断的。
按状态码查
4xx —— 你的请求有问题
| 状态码 | 含义 | 常见原因 | 怎么办 |
|---|---|---|---|
400 | 请求格式错误 | JSON 语法错、缺必填字段、参数类型不对 | 看 message，通常是某个字段写错了 |
401 | 未认证 | 没带 Authorization、密钥写错、令牌被删了 | 检查密钥；去控制台确认令牌还在 |
403 | 无权限 | 额度用完、令牌被禁用、模型不在你的分组里 | 检查额度和令牌状态 |
404 | 找不到 | 模型名不存在、路径写错 | 用 /v1/models 核对模型名 |
413 | 请求太大 | prompt 超长 | 缩减输入或换上下文更大的模型 |
422 | 参数不合法 | 比如 temperature 传了 5 | 按参数表改 |
429 | 被限流 | 请求太快，或上游饱和 | 退避重试，见限流与重试 |
5xx —— 服务端或上游的问题
| 状态码 | 含义 | 该怎么办 |
|---|---|---|
500 | 服务端内部错误 | 重试；持续出现请联系我们 |
502 | 上游网关错误 | 上游服务抖动，网关会自动重试 3 次；仍失败则稍后再试 |
503 | 服务不可用 | 上游全部渠道都不可用，等恢复 |
504 | 网关超时 | 不自动重试（重试大概率还是超时）。缩短输入或换模型 |
524 | 上游超过 120 秒未返回 | 不自动重试。提示词太长或模型太慢，查一下输入大小 |
530 | 上游 Cloudflare 隧道断开 | 会自动重试；连续出现说明上游真的挂了 |
502 / 530 是上游的事
这两个码说明我们的网关是活的，是上游服务商那边出了问题。我们已经在自动重试，你不用自己加重试次数。
常见 code 值
| code | 说明 |
|---|---|
invalid_token | 令牌无效或不存在 |
token_expired | 令牌过期了 |
insufficient_quota | 额度不足 |
model_not_found | 模型不存在或无权访问 |
rate_limit_exceeded | 触发限流 |
invalid_request_error | 请求体格式问题 |
context_length_exceeded | 输入超过模型上下文长度 |
content_filter | 被内容安全策略拦截 |
排查流程
按这个顺序看，能解决九成问题：
- 先看 HTTP 状态码 —— 4xx 是你的问题，5xx 是服务端/上游的
- 再看
error.message—— 通常直接说了原因 - 401 / 403：密钥对不对？令牌还在吗？额度够吗？
- 404：模型名用
/v1/models核对过吗？ - 429：是不是并发太高，或者令牌速率设太低？
- 5xx：等 1-2 分钟重试；超过 10 分钟找我们
自己验证的最小命令
怀疑服务有问题时，跑这条最简单的：
bash
curl -s -o /dev/null -w "%{http_code}\n" \
https://api.blueworkshop.top/v1/models \
-H "Authorization: Bearer $CYAN_API_KEY"200→ 服务和密钥都正常，问题在具体请求上401→ 密钥问题5xx→ 服务端问题
报错时请带上这些信息
联系支持时提供：状态码、完整错误 JSON、request id（响应头或错误信息里那个长串）、大致时间。有这几样能快速定位，只发一句「报错了」没法查。