Developer guide
错误代码
按状态代码采取措施和重试规则
如果上游返回 4xx·5xx，网关会原样传递该代码；其他情况下，则遵循下表中的规则。
400·401·403·404·413 是需要修正请求或配置的代码，而 409·429·5xx 是客户端等待后重新发送相同请求的代码。
错误正文的格式因规范而异，Anthropic 兼容路径的 error.type 由状态代码确定。
403 的原因通过 error.message 区分，限额和用量数值可在控制台界面中确认。
状态代码
| 代码 | 含义 | 措施 |
|---|---|---|
| 400 | 请求值无效。Anthropic 兼容模型列表的 limit 超出 1~1000 范围，或尝试通过 GET /responses/{responseId}?stream=true 继续流式接收已保存的响应。 | 请将值修改为范围内的值。请在不使用 stream 的情况下查询已保存的响应。 |
| 401 | 密钥缺失，或密钥已过期、已撤销。 | 请在 API 密钥页面确认密钥状态，并检查请求头名称和 Bearer 前缀。 |
| 403 | 没有模型访问权限、超出使用限额、积分不足，或不是语音所有者。 | 请通过 error.message 确认原因，并在下方“限额和用量确认”部分的页面中确认相关数值。 |
| 404 | 模型不存在或此密钥无法访问该模型（包括已停止支持的模型）。调用了不存在的路径，或请求保留期已超过 3 天的 CleviDrive 产物时，也会返回此错误。 | 请先通过 GET /models 确认可调用的模型列表。请将路径与“调用 API”页面中的表格进行核对。 |
| 408 · 409 · 413 | 上游超时、拥堵或请求大小超限。语音·Voice 路径的超时时间为 5 分钟，请求上限为 28 MiB。 | 如果 409 响应中包含 Retry-After，请等待相应时间后重新发送相同请求。对于 413，请拆分请求后发送。 |
| 429 | 上游提供商实施了速率限制。 | 如果包含 Retry-After，请等待相应时间后重试；如果没有，请使用指数退避策略重试。 |
| 5xx | 网关或上游的临时错误（包括 503）。 | 请使用指数退避策略重试。如果问题反复出现，请联系我们。 |
不会返回 402。积分不足和超出使用限额都将返回 403。
重试与联系我们
网关不会生成自身的 429，也不会代替您重试上游响应或将其加入队列。等待和重试由客户端执行。
联系我们时，请通过帮助与联系我们并提供 X-Request-Id。如果未发送 X-Request-Id，服务器签发的值位于 Anthropic 兼容响应的 request-id 请求头中。
错误正文
错误正文的格式因规范而异。对于上游错误，仅保留消息并整理后传递，不会传递堆栈或内部字段。
OpenAI 兼容路径的错误正文。
{
"error": {
"message": "API key is required.",
"type": "invalid_request_error"
}
}Anthropic 兼容路径的错误正文。error.type 根据状态代码按下表确定。
{
"type": "error",
"error": {
"type": "authentication_error",
"message": "..."
},
"request_id": "rqid..."
}| 状态代码 | error.type |
|---|---|
| 400 | invalid_request_error |
| 401 | authentication_error |
| 403 | permission_error |
| 404 | not_found_error |
| 413 | request_too_large |
| 429 | rate_limit_error |
| 529 | overloaded_error |
| 其他代码 | api_error |
查看限额和用量
限额数值因工作区而异。通过 error.message 确认 403 的原因后，请在以下页面查看数值。
| 查看项目 | 控制台页面 |
|---|---|
| 应用于工作区的限额 | 概览中的已分配使用限额 |
| 套餐允许的范围和余额 | 套餐和积分 |
| 实际用量（按模型、按密钥的调用量，预计扣除的积分） | 用量 |
| 密钥状态（是否已过期或撤销） | API 密钥 |