快速开始

故障排查

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

SDK 安装

现象检查项
npm 安装 @joytoken/* 返回 404 Not FoundTypeScript 包通过 GitHub 分发，不发布到 npm Registry。使用 SDK 快速开始中的 #path:/client-sdk-ts 或 #path:/agent-sdk-ts GitHub dependency。
Agent SDK 提示缺少 peer dependency将 @joytoken/agent-sdk-ts 和 @joytoken/client-sdk-ts 都声明为直接 GitHub dependency。
Go 无法解析旧 module使用 github.com/jd-opensource/joytoken-sdk-go，删除 github.com/joytoken/client-sdk-golang import。
Git dependency 内容发生非预期变化固定到 Release Tag 或 Commit，不要在生产构建中跟随默认分支。

快速检查

检查项应该是什么
Base URL从 环境 选择 JOY_TOKEN_OPENAI_BASE_URL
聊天接口POST /openai/v1/chat/completions
Responses 接口POST /openai/v1/responses（复数）
认证Authorization: Bearer $JOY_TOKEN_API_KEY
Content-Typeapplication/json
模型先用 auto 验证
请求体Chat Completions 使用非空 messages；Responses 使用 input
Request ID设置 X-Request-ID
钱包对应 tier 有余额
策略IP、tier、模型允许

状态码

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

最小复现

Responses API：

curl "$JOY_TOKEN_OPENAI_BASE_URL/responses" \
  -H "Authorization: Bearer $JOY_TOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: debug-minimal-responses-001" \
  -d '{
    "model": "auto",
    "input": "ping",
    "stream": false
  }'

Chat Completions：

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-openai-001" \
  -d '{
    "model": "auto",
    "messages": [{ "role": "user", "content": "ping" }],
    "stream": false
  }'

定位顺序

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

常见问题

问题优先检查
Responses 返回 404 page not found使用复数路径 /openai/v1/responses，不要使用 /openai/v1/response
一个来源能调，另一个来源 403来源 IP 或测试环境 Key 策略
具体模型 ID 被拒绝请求只接受 auto；模型列表 ID 仅供查看
auto 失败tier、策略、钱包和预算过滤后没有候选模型
流式前端卡住SSE 解析是否正确处理 metadata 和 [DONE]
Responses 流没有结束读取 response.output_text.delta，并在 response.completed 后结束
Usage 没有记录请求是否成功，是否使用同一把 Key