> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.joytokens.ai/llms.txt.

# 故障排查

> 常见接入问题、状态码和定位顺序

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

## SDK 安装

| 现象                                      | 检查项                                                                                                                        |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| npm 安装 `@joytoken/*` 返回 `404 Not Found` | TypeScript 包通过 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，不要在生产构建中跟随默认分支。                                                                                   |

## 快速检查

#### OpenAI

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

#### Anthropic

| 检查项          | 应该是什么                                                                 |
| ------------ | --------------------------------------------------------------------- |
| Base URL     | 从 [环境](/zh/user-guide/environments) 选择 `JOY_TOKEN_ANTHROPIC_BASE_URL` |
| Messages 接口  | `POST /anthropic/v1/messages`                                         |
| 认证           | `x-api-key: $JOY_TOKEN_API_KEY`                                       |
| Anthropic 版本 | `anthropic-version: 2023-06-01`                                       |
| Content-Type | `application/json`                                                    |
| 模型           | 先用 `auto` 验证                                                          |
| messages     | 必须非空                                                                  |
| 钱包           | 主钱包有余额                                                                |
| 策略           | IP、tier、模型允许                                                          |

## 状态码

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

## 最小复现

#### OpenAI

Responses API：

```bash
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：

```bash
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
  }'
```

#### Anthropic

```bash
curl "$JOY_TOKEN_ANTHROPIC_BASE_URL/messages" \
  -H "x-api-key: $JOY_TOKEN_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{ "role": "user", "content": "ping" }],
    "max_tokens": 1024,
    "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 策略                                          |
| 指定模型返回 `model_exhausted`          | 模型名是否与目录中的 `modelName` 完全一致，以及该模型是否有上游容量                    |
| `auto` 失败                         | tier、策略、钱包和预算过滤后没有候选模型                                      |
| 流式前端卡住                            | SSE 解析是否正确处理 metadata 和 `[DONE]`                            |
| Responses 流没有结束                   | 读取 `response.output_text.delta`，并在 `response.completed` 后结束 |
| Usage 没有记录                        | 请求是否成功，是否使用同一把 Key                                          |