Troubleshooting & FAQ

Every error's full contract is in Errors & rate limits; this page is the practical index — the symptom you see, the likely cause, the fix. Statuses link to the matching row there.

Requests#

401 with a key I just created. Keys are shown once and only a hash is stored — copy the full sk-hd-v1-… at creation. Check the header form (Authorization: Bearer sk-hd-v1-...), that nothing trimmed or lowercased it, and that the key was not revoked or has not expired. A refused key always answers identically, so nothing about the key can be probed from the outside — when in doubt, mint a new one.

402 although my balance looks fine. Three common shapes, distinguishable by metadata:

• No scope, metadata.required above metadata.spendable — the credit hold (prompt + your max_tokens ceiling) exceeded the spendable balance, which subtracts outstanding holds. Lower max_tokens, or top up.
• scope: "key", "workspace" or "account" — a spend limit was reached; limit_reset says when the window clears.
• It can also be a genuinely empty balance — check the five balance figures on the Credits tab, not just "available".

404 for a model I can see on the site. The id probably names a family — families are for browsing; a request must name a served model. The error's metadata.family_variants lists the served ids to use instead. Otherwise: ids are author/slug (or provider/slug), case-insensitive, and every : segment other than the routing suffixes is part of the id itself. :online returns 400 because web search plugins are unsupported.

400 for a request that works elsewhere. If it names provider, check for an unknown key inside it — the whole object is validated strictly. Otherwise see the body against the parameter ranges in the API reference; a provider rejecting the request as invalid surfaces as 400 provider_error with the provider's own message attached.

413 on an upload. Request bodies are capped at 8 MB; audio files at 25 MiB. Images ride inside the body as base64, which inflates them by a third — resize before embedding.

429. Your key (600 requests/minute) or, unauthenticated, your address (120/minute). Honour Retry-After, read the X-RateLimit-* headers, and reduce round-trips — embeddings accept input arrays; longer turns beat many tiny ones.

502 / 503 / 504. Worth retrying with backoff — routing re-runs per attempt. 503 with metadata.rejections means the model exists but no live endpoint satisfied your constraints; the rejections name the rule that eliminated each endpoint (zdr_required, max_price_exceeded, …), so you know what to loosen. If it persists, the status board shows the market's health at a glance.

502 saying the provider "does not serve" the API. That model's endpoints include one that only serves chat — completions, embeddings and transcriptions are chat's siblings, not guaranteed everywhere. Pick a model whose endpoints serve the API you are calling, or add fallbacks.

Streaming#

The stream ended without data: [DONE]. It was cut off — treat it as failed, not complete. Retry the request.

A chunk contained an error. Terminal in-band failure: the provider died mid-generation. Delivered output is billed, and a stream that produced nothing has its token charges waived. See streaming.

I aborted a stream — what did it cost? Tokens generated before the abort are billed; the generation is recorded as cancelled, and its cost is queryable with X-Generation-Id at GET /generation.

Money#

What did one specific request cost? usage.cost on the response (final chunk, streamed), or the generation record afterwards via X-Generation-Id.

A deposit has not appeared. Transfers credit when observed and confirmed on a supported network — check the network first: a transfer on any other network cannot be credited or recovered. An exchange withdrawal cannot be matched automatically (you cannot sign for its address); it needs support, with the transaction hash and the network. The full guide is Deposits.

How do I cap what an integration can spend? A spend limit on its key, optionally with a daily/weekly/monthly UTC reset; harder fences at workspace and account scope. Set them from the Keys tab or the workspace.

Do free endpoints really cost nothing? Yes. An endpoint whose document declares it free bills zero for every unit that document prices, whatever figures stand beside the declaration, and :free routes only to those — an endpoint that merely publishes zeros bills them and the suffix passes it by. Watch the two edges: a 503 when none is live, and zero token prices on a transcription (which bills per audio second, never per token).

Account#

I lost a key. Revoke it and mint a new one — only a hash is kept, so nothing can be shown again. Revocation is permanent and immediate; ledger history keeps its attribution.

Where does the chat playground's history live? In the browser you used — its own storage only, nothing server-side. Clearing the browser clears it; another browser never sees it.

Can I rename my organization? Organization names and slugs are fixed at creation; renaming is not available. Workspaces can be renamed.

Something charged wrong. Find the usage row in your ledger, take its generation id, and inspect the full record at GET /generation. For anything that still looks wrong, quote the X-Generation-Id — it addresses the request end to end.

Selling#

How do I get my models listed? Apply as a provider from your account, then serve the model-list document. The whole contract — schema, pulls, health, payouts — is on that page and the ones it links.

My pull reports findings. Each entry validates independently; the run's issue list names the entry and field. The operating guide maps the common findings to their fixes.