Troubleshooting

Find your symptom below and apply the fix. Most Tokens API errors come with a specific error.code in the response body, and the code tells you more than the HTTP status, so start by reading it:

curl -i https://tokens.bd/v1/models -H "Authorization: Bearer $TOKENS_API_KEY"

-i also prints x-tokens-request-id. Keep it, because support will ask for it. If many things are failing at once, check /status before you debug your own setup.

401: missing_api_key or invalid_api_key#

Symptom: every request fails immediately, including GET /v1/models.

Fix:

• missing_api_key: no key reached the gateway. Send it as Authorization: Bearer <key> or x-api-key: <key>. In a shell, run echo $TOKENS_API_KEY (or echo $env:TOKENS_API_KEY in PowerShell) to check the variable isn't empty in this session.
• invalid_api_key: the key is wrong, revoked, or was rotated. Keys start with tok_live_ followed by 48 hex characters. Look for a truncated paste, stray quotes or a trailing newline. After a rotation the old secret stops working immediately, so update every client. Lost a key? Keys are shown once, so create a new one in /dashboard/keys.

403: model_not_allowed_on_key or tier_permission_denied#

Symptom: some models work and others return 403.

Fix:

• model_not_allowed_on_key: the key was created with an allowed-models list that doesn't include this model. Allow-lists can't be edited after creation, so create a new key with the models you need.
• tier_permission_denied: your plan doesn't include this model and you have no wallet balance to pay for it. Pick a model your plan includes, add funds to the wallet, or change plans in /dashboard/billing. See Plans and wallet.
• monthly_spend_cap_exceeded: the key reached its monthly spend cap. Wait for the next month or use a key with a higher cap.
• key_inactive, key_expired, account_suspended: the key or account has been disabled. Contact support.

GET /v1/models lists exactly the models this key can use right now, which settles most 403 questions quickly.

402: insufficient_credits#

Symptom: requests that used to work start failing with 402. Related codes are no_funding (no active plan and no funded wallet), outstanding_debt (settle the balance shown in the message) and member_cap_reached.

Fix: your plan credits and wallet can't cover the request. Top up or renew in /dashboard/billing. The minimum top-up is $5 / ৳500. Subscriptions are one-time payments per period and don't renew on their own, so a plan that has quietly expired looks exactly like this.

Replies cut short while your balance is low are the same problem in milder form: the gateway lowers max_tokens to what the balance covers (floor 16). Top up, and set a low-balance alert under Notifications.

429: window_exhausted vs rate_limited vs concurrency_limit#

Three different 429s with three different fixes. Read error.code and the Retry-After header. Tokens doesn't send X-RateLimit-* headers.

Limits apply per account, not per key, so creating more keys won't raise them. Details are in Rate limits. A 429 with code rate_limit_exceeded comes from the upstream provider. The gateway already tried to fail over, so retry after a short pause or try another model.

404: model_not_found#

Symptom: model_not_found (or 400 model_not_available) for a model you're sure exists.

Fix: model IDs are exact and include the provider prefix, for example deepseek/deepseek-v4.1-flash, not deepseek-v4.1-flash. List the IDs your key can actually use:

curl -s https://tokens.bd/v1/models -H "Authorization: Bearer $TOKENS_API_KEY" | jq -r '.data[].id'

model_not_available means the ID is valid but the model can't be served right now. Pick another one from /models.

A 404 unsupported_endpoint is different. It means the path isn't one Tokens serves (images, audio, files, batches, assistants, fine-tuning and moderations aren't supported), or the base URL is wrong. See the next section.

Agent says "model not found" or 404: wrong base URL#

This is the most common setup mistake. Tools fall into two groups:

Using /v1 with Claude Code produces requests to /v1/v1/messages. Leaving /v1 off in an OpenAI tool sends requests to /chat/completions on the site root. Both end in a 404 that many agents report as "model not found". Check the config file for the agent you use (Claude Code), or let the Tokens CLI write it for you.

502, 503, 504: upstream errors#

Codes: 502 upstream_unreachable, 503 no_upstream_available, 504 upstream_timeout. The gateway fails over to another upstream source on 429, 502, 503, 504 and connection errors before replying. If you still get a 5xx, every source it tried failed. Retry with backoff (two or three attempts), try a different model, and check /status for an incident affecting upstream providers. If the error persists for a single model, open a ticket with the x-tokens-request-id.

Long requests are fine. The gateway waits up to 600 seconds for response headers. If your own client times out first, raise its timeout or switch to streaming.

Streaming hangs or arrives all at once#

Symptom: a streamed response shows nothing for a long time and then appears in one block, or never finishes.

Fix: something between your client and Tokens is buffering the server-sent events.

• Test with curl -N and "stream": true first (cURL). If that streams, the problem is in your stack.
• Behind your own nginx: set proxy_buffering off; for the route, or send X-Accel-Buffering: no from your app.
• Don't gzip text/event-stream responses in your own middleware.
• Corporate proxies and some antivirus HTTPS scanners buffer whole responses. Try another network to confirm.
• In your own route handlers, forward chunks as they arrive instead of collecting the full body. See Node.js and Streaming.

Tool calls fail or are ignored#

Symptom: a 400 error mentioning tools, or the model answers in plain text and never calls your function.

Fix: not every model supports tool calling. Check the model's page in /models and switch to one that lists tool support. Then check your schema: parameters must be a valid JSON Schema object, and each tool result has to be sent back with the matching tool_call_id. It's also why an agent can chat but never edit files. See Tool calling.

Windows: environment variable isn't picked up#

• $env:TOKENS_API_KEY = "tok_live_your_key" sets it for the current PowerShell window only.
• setx TOKENS_API_KEY "tok_live_your_key" saves it for new windows only. The window you ran it in doesn't see it, so open a new terminal (and restart VS Code or your agent).
• In cmd.exe, set TOKENS_API_KEY=tok_live_your_key has no quotes around the value. Any quotes become part of the key.
• In Windows PowerShell 5.1, curl is an alias for Invoke-WebRequest. Use curl.exe for the examples in these docs.

Still stuck#

Open a ticket from /dashboard/support with the x-tokens-request-id, the time, the model ID and the error.code. Don't include your API key. Support explains what to send, and Errors has the full code reference.