Overview

Troubleshooting

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

Quick Check

CheckExpected value
OpenAI-compatible base URLJOY_TOKEN_OPENAI_BASE_URL from Environments
Chat endpointPOST /openai/v1/chat/completions
AuthAuthorization: Bearer $JOY_TOKEN_API_KEY
Content-Typeapplication/json
ModelTest with auto first
messagesMust be non-empty
Request IDSend X-Request-ID
WalletTarget tier has balance
PolicyIP, tier, and model are allowed

Status Codes

StatusCommon causeFix
400Bad JSON, empty messages, oversized bodyFix request
401No API keyCheck auth header
402Wallet or budget insufficientTop up, lower tier, adjust budget
403Key, IP, tier, or model policy rejectedCheck API key policy
405Wrong methodChat completions must use POST
502Routing or upstream failureShort backoff retry, record request ID
503 / 504Service unavailable or timed outExponential backoff retry

Minimal Reproduction

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

Debugging Order

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

Common Questions

QuestionCheck first
Works locally, 403 in productionProduction egress IP or production key policy
auto works, pinned model failsfixed model, blacklist, model availability
pinned model works, auto failsno candidate models after tier, policy, balance filters
Streaming frontend hangsSSE parsing handles metadata and [DONE]
Usage is missingRequest succeeded and used the same key