错误码对照

HTTP 状态码 + detail 含义 + 客户端应该怎么处理。

错误响应格式

当前 Router/API 使用 FastAPI 标准错误结构，错误描述主要位于 detail 字段。客户端应优先按 HTTP 状态码处理，再读取 detail 做日志和提示。

json

{
  "detail": "Insufficient wallet balance"
}

HTTP	detail / 语义	含义	客户端动作
400	invalid request	请求 JSON 格式错 / 必填参数缺失	不重试，修代码
400	context length exceeded	prompt + max_tokens 超过模型上下文	换更大窗口模型，或截断 prompt
400	model not found	model 名称不存在	查 `GET /v1/models` 确认可用模型
400	content policy violation	内容被审核模块拦截（仅开启审核时）	调整 prompt，或换审核宽松的模型
401	Missing / invalid API key	Authorization header 缺失 / Key 拼错	检查 Bearer token
401	Invalid API key	Key 已删除 / 已过期	Console 重新生成
402	Insufficient wallet balance	钱包余额不足本次预扣	去 Console 充值
403	Model not available	请求的模型未上架、不可见，或没有平台价格	到模型列表确认模型状态和定价
403	Model not available	请求中的模型当前不可调用	换用已上架且已定价的模型
404	Not Found	URL 写错，比如少了 `/v1`	检查 base_url
429	Rate limit exceeded	RPM 或 TPM 超限	按 `Retry-After` header 指数退避
500	Internal Server Error	Router 内部错（已被监控）	立即重试 1-2 次
502	Upstream unavailable	当前模型没有可用上游候选	退避 10s+ 重试，或检查模型、provider 控制和上游状态
503	Service unavailable	Router 过载 / 维护窗口	退避 30s+ 重试
504	Upstream timeout	上游超过 timeout 阈值仍未返回	退避 5s 重试，或换模型
499	Client closed request	客户端主动断连（Nginx 约定码）	日志里有记录，按实际消耗结算

速率限制触发时当前返回 429 和 detail。不要依赖X-RateLimit-* 响应头；如果后续版本补充这些头，会在本文档中单独标注。

http

HTTP/1.1 429 Too Many Requests
content-type: application/json
x-request-id: req_xxxx

{"detail":"Rate limit exceeded (600/min)"}

请求 ID 是线索

每次响应头都有 x-request-id: req_xxxx。复制后到 Console → 请求日志搜，能看到：