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

# Troubleshooting

> Common integration issues, status codes, and debugging order

First confirm whether the request reached JoyToken. Then determine whether the issue is authentication, policy, wallet, routing, upstream, or client parsing.

## SDK Installation

| Symptom                                       | Check                                                                                                                                                                             |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| npm returns `404 Not Found` for `@joytoken/*` | The TypeScript packages are distributed from GitHub, not the npm registry. Use the GitHub `#path:/client-sdk-ts` or `#path:/agent-sdk-ts` dependency shown in the SDK quickstart. |
| Agent SDK reports a missing peer dependency   | Declare both `@joytoken/agent-sdk-ts` and `@joytoken/client-sdk-ts` as direct GitHub dependencies.                                                                                |
| Go cannot resolve the old module              | Use `github.com/jd-opensource/joytoken-sdk-go`; remove `github.com/joytoken/client-sdk-golang` imports.                                                                           |
| A Git dependency changes unexpectedly         | Pin a release tag or commit instead of following the default branch.                                                                                                              |

## Quick Check

#### OpenAI

| Check              | Expected value                                                            |
| ------------------ | ------------------------------------------------------------------------- |
| Base URL           | `JOY_TOKEN_OPENAI_BASE_URL` from [Environments](/user-guide/environments) |
| Chat endpoint      | `POST /openai/v1/chat/completions`                                        |
| Responses endpoint | `POST /openai/v1/responses` (plural)                                      |
| Auth               | `Authorization: Bearer $JOY_TOKEN_API_KEY`                                |
| Content-Type       | `application/json`                                                        |
| Model              | Test with `auto` first                                                    |
| Request body       | Chat Completions uses non-empty `messages`; Responses uses `input`        |
| Request ID         | Send `X-Request-ID`                                                       |
| Wallet             | Main wallet has balance                                                   |
| Policy             | IP, tier, and model are allowed                                           |

#### Anthropic

| Check             | Expected value                                                               |
| ----------------- | ---------------------------------------------------------------------------- |
| Base URL          | `JOY_TOKEN_ANTHROPIC_BASE_URL` from [Environments](/user-guide/environments) |
| Messages endpoint | `POST /anthropic/v1/messages`                                                |
| Auth              | `x-api-key: $JOY_TOKEN_API_KEY`                                              |
| Anthropic version | `anthropic-version: 2023-06-01`                                              |
| Content-Type      | `application/json`                                                           |
| Model             | Test with `auto` first                                                       |
| messages          | Must be non-empty                                                            |
| Wallet            | Main wallet has balance                                                      |
| Policy            | IP, tier, and model are allowed                                              |

## Status Codes

| Status        | Common cause                                            | Fix                                           |
| ------------- | ------------------------------------------------------- | --------------------------------------------- |
| `400`         | Bad JSON, missing `input` or `messages`, oversized body | Fix request                                   |
| `401`         | No API key                                              | Check auth header                             |
| `402`         | Wallet or key budget insufficient                       | Top up the wallet, adjust budget              |
| `403`         | Key, IP, tier, or model policy rejected                 | Check API key policy                          |
| `405`         | Wrong method                                            | Use `POST` for the selected protocol endpoint |
| `502`         | Routing or upstream failure                             | Short backoff retry, record request ID        |
| `503` / `504` | Service unavailable or timed out                        | Exponential backoff retry                     |

## Minimal Reproduction

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

## Debugging Order

1. Search JoyToken Console logs by `X-Request-ID`.
2. Confirm the API key is active.
3. Check IP, tier, and model blacklist.
4. Check wallet balance and key budget.
5. Inspect `metadata.model` and billing metadata on successful responses.
6. Confirm usage is attributed to the same API key.

## Common Questions

| Question                                  | Check first                                                                        |
| ----------------------------------------- | ---------------------------------------------------------------------------------- |
| Responses returns `404 page not found`    | Use the plural path `/openai/v1/responses`, not `/openai/v1/response`              |
| Works from one source, `403` from another | Source IP or key policy                                                            |
| Pinned model returns `model_exhausted`    | The name matches a catalog `modelName` exactly and the model has upstream capacity |
| `auto` fails                              | no candidate models after tier, policy, wallet, and budget filters                 |
| Streaming frontend hangs                  | SSE parsing handles metadata and `[DONE]`                                          |
| Responses stream does not finish          | Read `response.output_text.delta` and stop after `response.completed`              |
| Usage is missing                          | Request succeeded and used the same key                                            |