错误 | JoyToken | Documentation

JoyToken 模型调用失败时返回 OpenAI 兼容错误结构。message 是可读原因，type 是客户端更适合判断的稳定错误类型。

Error response

1 {
2   "error": {
3     "message": "missing api key",
4     "type": "missing_api_key"
5   }
6 }

聊天补全错误

HTTP 状态码	`error.type`	常见原因	是否建议重试
`400`	`invalid_request_error`	请求体不是合法 JSON、body 超过 8 MiB、`messages` 为空	否
`401`	`missing_api_key`	没有提供 API Key	否
`403`	`invalid_api_key`	API Key 无效，或状态不是 `ACTIVE`	否
`403`	`policy_rejected`	blocked 策略、IP 不允许、模型黑名单、tier 不允许、固定模型不匹配	否
`402`	`insufficient_quota`	每日/每周额度超限，或当前 tier 钱包余额不足	否，先调整余额/策略
`502`	`routing_error`	路由器没有返回可用模型，或路由服务错误	可短退避重试
`502`	`upstream_error`	提供方调用失败，或下游 gRPC 错误被网关转换	可短退避重试
`503`	`upstream_error`	下游服务不可用	是
`504`	`upstream_error`	下游调用超时	是
`500`	`stream_error`	当前响应 writer 不支持流式响应	否，通常是部署/代理问题

OpenAPI 里保留了 429 作为传统 rate limit 的兼容状态，但当前代码路径里更明确执行的是 quota、policy 和 wallet precheck；固定 QPS 限流还不是当前公开能力。

模型列表错误

GET /api/v1/models 由 front-gateway 暴露，不需要 API Key。当前最常见的错误是后台模型服务不可用：

503 response

1 {
2   "code": 50300,
3   "message": "admin-bff not available"
4 }

排障字段

请求失败时建议记录下面这些字段，并在 Console 的日志/用量页中按同一时间窗口查询：

字段	来源
`X-Request-ID`	请求头，或网关生成的内部 request id
`model` / `tier`	请求体
HTTP 状态码	响应状态码
`error.type` / `error.message`	错误响应体
`X-DAOE-Used-Model` / `X-DAOE-Used-Provider`	成功响应头，用于确认实际命中
`metadata.billing`	成功响应体，用于确认 token 和 Credits

简单重试判断

retry.ts

1 export function shouldRetryJoyTokenError(status: number, type?: string) {
2   if (status === 503 || status === 504) return true;
3   if (status === 502 && (type === "routing_error" || type === "upstream_error")) {
4     return true;
5   }
6   return false;
7 }