概览

故障排查

排障时先确认请求有没有进入 JoyToken，再判断是认证、策略、钱包、路由、提供方还是客户端解析问题。

快速检查

检查项应该是什么
基础 URLhttps://api-dev.joytokens.ai/openai/v1
聊天接口POST /chat/completions，完整路径是 /openai/v1/chat/completions
认证Authorization: Bearer $JOY_TOKEN_API_KEY
Content-Typeapplication/json
模型先用 auto 验证，再换具体 model_key
消息messages 必须非空
Request ID设置 X-Request-ID，方便查网关日志和用量
钱包对应个人或组织钱包有余额
策略IP、tier、固定模型、模型黑名单是否允许

状态码

状态码常见原因处理方式
400JSON 不合法、messages 为空、body 超过 8 MiB对照 Chat Completions 示例重新构造请求
401没有 API Key检查 Authorization 或 X-API-Key
402钱包余额不足、预算不足、预冻结失败充值、降低 tier、改用 auto，或检查 billing account
403Key 非 active、IP 不允许、tier 不允许、固定模型不匹配、模型黑名单检查 API Key 策略快照
405方法错误聊天补全必须使用 POST
502路由器返回异常、provider-adapter 或上游调用失败查 request ID、selected model、提供方和上游错误
503下游服务不可用，例如 admin-bff 未配置或 gRPC unavailable稍后重试或检查服务状态
504下游超时降低请求复杂度、开启流式响应，或检查提供方状态

错误响应形态

模型调用错误保持 OpenAI 兼容风格：

Error response
1{
2  "error": {
3    "type": "policy_rejected",
4    "message": "requested tier is not allowed"
5  }
6}

模型列表接口 /api/v1/models 使用 front-gateway 的统一响应结构：

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

日志关联

服务端请求建议始终带一个业务可读的 request ID：

Traceable request
$curl https://api-dev.joytokens.ai/openai/v1/chat/completions \
>  -H "Authorization: Bearer $JOY_TOKEN_API_KEY" \
>  -H "Content-Type: application/json" \
>  -H "X-Request-ID: prod-chat-20260629-0001" \
>  -d '{
>    "model": "auto",
>    "messages": [{ "role": "user", "content": "ping" }]
>  }'

然后按这个顺序查：

  1. api-gateway 日志：是否收到请求，Key 来源是 Bearer 还是 X-API-Key。
  2. API Key 校验：valid、status、api_key_id、tier。
  3. 策略：IP、tier、固定模型、黑名单。
  4. 路由：是否返回 selected_model。
  5. 钱包：是否通过余额预检查和冻结。
  6. 提供方：实际 X-DAOE-Used-Model 和 X-DAOE-Used-Provider。
  7. 用量 / 账单：是否记录用量、是否结算冻结。

常见问题

问题解释
本地能调，线上 403线上出口 IP 不在策略白名单，或 Key 的 tier/模型策略不同
auto 可以，固定模型失败API Key 固定模型、模型黑名单或模型池没有该模型
固定模型可以，auto 失败策略/tier 过滤后没有可用模型，或路由器没返回 selected_model
流式前端卡住客户端没有正确处理 SSE，或把元数据事件当成 assistant delta
Usage 里没有记录提供方失败、流式 usage 不完整、billing calculate/record_usage 失败，或请求还在异步结算
钱包余额明明有但失败检查余额所在 tier 是否和 selected tier 一致

最小复现

排查时先用最小请求排除 SDK 和业务代码问题：

Minimal request
$curl https://api-dev.joytokens.ai/openai/v1/chat/completions \
>  -H "Authorization: Bearer $JOY_TOKEN_API_KEY" \
>  -H "Content-Type: application/json" \
>  -H "X-Request-ID: debug-minimal-001" \
>  -d '{
>    "model": "auto",
>    "messages": [{ "role": "user", "content": "ping" }],
>    "stream": false
>  }'

如果最小请求成功，再逐步加回 tier、tools、streaming、长上下文和固定模型。