概览

故障排查

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

快速检查

检查项应该是什么
OpenAI 兼容 Base URL从 环境 选择 JOY_TOKEN_OPENAI_BASE_URL
聊天接口POST /openai/v1/chat/completions
认证Authorization: Bearer $JOY_TOKEN_API_KEY
Content-Typeapplication/json
模型先用 auto 验证
messages必须非空
Request ID设置 X-Request-ID
钱包对应 tier 有余额
策略IP、tier、模型允许

状态码

状态码常见原因处理方式
400JSON 错误、messages 为空、body 过大修正请求
401没有 API Key检查认证 header
402钱包或预算不足充值、降低 tier、调整预算
403Key、IP、tier、模型策略不允许检查 API Key 策略
405方法错误聊天补全必须使用 POST
502路由或上游失败短退避重试，记录 request ID
503 / 504服务暂时不可用或超时指数退避重试

最小复现

$curl "$JOY_TOKEN_OPENAI_BASE_URL/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
>  }'

定位顺序

  1. 用 X-Request-ID 在 JoyToken Console 查日志。
  2. 确认 API Key 是否 active。
  3. 检查 IP、tier、fixed model、模型黑名单。
  4. 检查钱包余额和 Key 预算。
  5. 看成功响应里的 X-DAOE-Used-Model 和 X-DAOE-Used-Provider。
  6. 看用量是否归因到同一把 API Key。

常见问题

问题优先检查
本地能调，线上 403线上出口 IP 或生产 Key 策略
auto 可以，固定模型失败fixed model、黑名单、模型可用性
固定模型可以，auto 失败tier、策略、余额过滤后没有候选模型
流式前端卡住SSE 解析是否正确处理 metadata 和 [DONE]
Usage 没有记录请求是否成功，是否使用同一把 Key