Troubleshooting | JoyToken

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

Anthropic

Check	Expected value
Base URL	`JOY_TOKEN_OPENAI_BASE_URL` from 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	Target tier 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 budget insufficient	Top up, lower tier, 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

Anthropic

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

Debugging Order

Search JoyToken Console logs by X-Request-ID.
Confirm the API key is active.
Check IP, tier, and model blacklist.
Check wallet balance and key budget.
Inspect metadata.model and billing metadata on successful responses.
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
Concrete model ID is rejected	Requests accept only `auto`; catalog IDs are informational
`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