API reference
Get back to building.
Understand authentication, setup and request failures without guessing.
HTTP status codes
#| Status | Meaning | Next step |
|---|---|---|
| 400 | Invalid JSON, model or protocol | Check the body and the current model catalog. |
| 401 | Missing, invalid, revoked or expired key | Use an active XEDOC API key. |
| 402 | Insufficient available token balance | Check Overview. Active requests can hold balance; lower the requested output limit or ask an administrator to adjust your balance. |
| 403 | API access awaiting activation or access denied | Check the account status in your dashboard. |
| 404 | Unsupported route | Use one of the documented endpoints. |
| 413 | Request body too large | Reduce input or attachment size. |
| 429 | Request limit reached | Respect Retry-After and reduce request frequency. |
| 502 | The model service failed or its response was interrupted | Inspect the failure before deciding whether a retry is safe. |
| 503 | Generation/model paused, provider unavailable or coordination unavailable | Respect Retry-After when present and check availability. |
Read the error body
#{
"detail": "Your API access is awaiting activation"
}Gateway validation errors use a detail field. Model-service or streaming protocol errors may use an error object or an SSE error event. Handle the HTTP status and the format for the endpoint you are using. Never log Authorization headers or the full API key.
Client setup
#| Symptom | What to check |
|---|---|
| npx.ps1 cannot be loaded | Use npx.cmd in PowerShell. |
| No characters appear while pasting the key | Input is hidden. Paste once and press Enter. |
| xedoc command not found | Open a new terminal, check npm’s global bin PATH, or use npx. |
| The model picker is missing XEDOC models | Run setup for that client, fully quit it and reopen. |
| Codex cannot execute the credential helper | Check Node is installed at the saved path; rerun setup after moving or updating Node. |
| Claude Code works but Desktop does not | Configure Claude Desktop separately; its Code connection does not use settings.json. |
| A configuration cannot be parsed | Fix the reported client file or restore a valid backup; setup will not overwrite malformed JSON/TOML. |
| A managed desktop app ignores local changes | Ask the organization administrator about the effective inference policy. |
Limits and recorded usage
#Generation limits apply to the account across its keys and gateway instances. Creating extra keys does not multiply the account allowance. Follow Retry-After rather than retrying in a tight loop.
Your token balance is separate from raw model usage. The charge applies the model’s input, cached-input and output factors; cached input is counted once. For example, 100,000 tokens at ×5 costs 500,000 balance tokens. Request details show the rates used for that request.
A request reserves credit for its input and output limit before it starts. Unused reserved credit is released when final usage is known. If no output limit is supplied, the gateway sets a 4,096-token output limit. Image attachments and stored conversation references can require a larger input hold. Requests with unknown final usage remain pending reconciliation; older requests are marked Not billed.
Requests records known token usage and status without storing prompt or response text. Unknown usage is shown as unknown, not invented as zero. You can inspect request metadata in Dashboard → Requests.