API reference
API errors and troubleshooting
Resolve API key errors, insufficient token balance, rate limits and client setup problems using HTTP status codes and request details.
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 your balance in Overview. New requests require a positive balance and enough credit for the locally estimated text input cost including the model multiplier. For an estimated-input rejection, shorten the input or add credit. The balance stops at zero; calculated usage above the amount charged is not a debt. A top-up or license adds its full token value. |
| 403 | API access disabled or model 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": "API access is disabled for your account. Contact an administrator."
}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, or run the npx install command again. |
| 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
#The default is 20 generation requests per minute per account, shared across models, protocols, API keys and gateway instances. An administrator can change your limit under Users → Manage. Creating extra keys does not multiply the allowance. At most 20 generation requests can run simultaneously per account, subject to shared service capacity. A limit rejection does not charge tokens. 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.
Before generation, XEDOC locally estimates tokens in the supplied text and applies the model input multiplier. If the estimated input cost exceeds your current balance, the request returns HTTP 402 without generating or charging tokens. Shorten the input or add credit. This estimate can differ from provider usage and does not include opaque media or server-side conversation history. It is used only for admission; Requests and billing use actual provider usage. Accepted requests start without a token reservation or an added output limit. Complete provider usage is calculated once when the request finishes. The amount deducted is capped at the remaining balance, which never becomes negative. New requests stop at zero. Request details distinguish calculated usage cost, tokens charged and any amount not charged. Once the balance is exhausted, older requests cannot consume a later top-up. License credits and top-ups add their full value. Redeeming a license does not change your API keys. Unknown final usage is marked Usage unavailable or Needs review without blocking the balance; 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.