Errors
Errors are returned in the format you called: Anthropic-format endpoints return Anthropic-style error bodies, and OpenAI-compatible endpoints return OpenAI-style ones. Failed requests are not charged.
| Status | code | Description |
|---|---|---|
| 400 | invalid_json / model_required | The request body is not valid JSON, or the model field is missing |
| 400 | model_not_supported | This model is not supported: the model id is misspelled, not listed, or not a Claude model (only the Claude family is offered). Not forwarded, not charged |
| 401 | invalid_api_key | The key does not exist, is malformed, or has been deleted |
| 401 | api_key_expired | The key has passed its expiry date |
| 402 | insufficient_balance | Insufficient balance; requests resume automatically after you top up |
| 402 | key_quota_exceeded | This key has reached its spend limit; you can raise it in the console |
| 403 | api_key_disabled | The key is disabled |
| 403 | account_suspended | The account is suspended |
| 413 | request_too_large | The request body exceeds 32 MB |
| 429 | upstream_rate_limited | The service is busy (too many requests) and a backup route was already tried. May carry retry-after (seconds) / retry-after-ms (milliseconds) headers; wait as they say, then retry. Not charged |
| 502 | upstream_unavailable | The upstream is temporarily unavailable and a backup route was already tried; retry later |
| 503 | no_upstream_channel | No upstream is currently available to serve this model |
| 503 | upstream_overloaded | The service is temporarily overloaded and a backup route was already tried. May carry retry-after (seconds) / retry-after-ms (milliseconds) headers; wait as they say, then retry. Not charged |
| 504 | upstream_timeout | A non-streaming request through Cloudflare returned nothing within 115 seconds. It was stopped, not charged, and is not retried automatically (inference requests are kept alive and never get this; only requests that cannot be kept alive can) |
// OpenAI-compatible format { "error": { "message": "Insufficient balance", "type": "insufficient_balance", "code": "insufficient_balance" } } // Anthropic format { "type": "error", "error": { "type": "billing_error", "message": "Insufficient balance", "code": "insufficient_balance" } }
If an error of the same kind occurs midway through an HTTP 200 stream, you receive an error event or an error object with the same code (upstream_rate_limited or upstream_overloaded): Anthropic and Responses formats send an event: error event, while OpenAI chat sends a data chunk carrying an error object. Whatever was generated before that point is billed as usual.
Every response carries an x-tokenarmy-request-id header; include it when reporting a problem.
Cloudflare error pages
If you receive a Cloudflare HTML page (response header server: cloudflare, no x-tokenarmy-request-id), the request ended at the edge and you were not charged. The most common case is 524: the response had not started after 125 seconds. For long outputs use "stream": true and retry later. A stream that sends no data for 125 seconds is also disconnected; what was already generated is billed as usual and can be checked in the request log in the console.