错误码

primerouter 的错误响应与 OpenAI 同构，便于现有代码无修改使用。

标准错误格式

json

{
  "error": {
    "type": "invalid_request_error",
    "message": "Model 'qwen-max-x' not found",
    "code": "model_not_found",
    "param": "model"
  }
}

常见 HTTP 状态码

状态	type	含义	处理建议
400	invalid_request_error	请求格式错误 / 模型不存在 / 参数非法	检查 model 名、JSON schema
401	authentication_error	API key 无效、过期、未提供	检查 Authorization header
402	insufficient_quota	配额耗尽	充值或分配更多额度
403	permission_denied	key 有效但无权（模型限制 / IP 白名单 / 分组）	调整 key 设置
404	not_found_error	端点不存在	检查 URL
429	rate_limit_exceeded	限流	看 `Retry-After` header，指数退避
500	api_error	primerouter 内部错误	重试 1-2 次
502 / 503	upstream_error	上游供应商不可用	primerouter 已自动尝试故障转移；仍失败说明所有候选渠道都不可用
504	timeout_error	上游响应超时	重试

限流细节

429 响应带：

Retry-After: 30
X-RateLimit-Limit-Requests: 60
X-RateLimit-Remaining-Requests: 0
X-RateLimit-Reset-Requests: 30s
X-RateLimit-Limit-Tokens: 60000
X-RateLimit-Remaining-Tokens: 0
X-RateLimit-Reset-Tokens: 60s

读 Retry-After 决定等多久；建议加随机抖动避免雷霆。

上游错误透传

当上游返回 4xx/5xx，primerouter 会：

尝试切到下一个候选渠道（如有）
全部尝试失败后，把最后一次上游错误信息透传给你（保留 code、message）
在响应 header 加 x-upstream-attempts: <n> 表示重试了几次

trace_id

每个响应都带：

X-Request-Id: 01J9XQH3M8K4N5P6Q7R8S9T0V1

报问题时把这个 ID 带上能直接定位到日志。

本地化

错误 message 默认英文。如要中文 / 其他语言：

http

Accept-Language: zh-CN

支持 7 种语言，与产品 i18n 一致。

完整错误列表

更详细的 code 字段含义参见 API Reference 中各端点的 responses 部分。

错误码 ​

标准错误格式 ​

常见 HTTP 状态码 ​

限流细节 ​

上游错误透传 ​

trace_id ​

本地化 ​

完整错误列表 ​