Errors and rate limits
Errors are JSON with a stable type:
{"error": {"type": "rate_limit_exceeded", "message": "Rate limit of 60 requests/min exceeded for this key; retry in 17s",
"limit": 60, "retry_after": 17}}
(Request-validation errors use FastAPI's 422 {"detail": [...]} shape.)
| Status | type |
Meaning | Retry? |
|---|---|---|---|
| 400 | invalid_request / (detail) |
malformed question or state | no — fix the request |
| 400 | invalid_model |
unknown model (see models) |
no |
| 401 | authentication_error |
missing, invalid or revoked key | no |
| 402 | insufficient_balance |
prepaid credit balance is $0 | after topping up |
| 402 | payment_required |
account payment problem | after updating billing |
| 403 | subscription_inactive |
subscription canceled / suspended | no |
| 422 | (detail) | schema validation failed | no |
| 429 | rate_limit_exceeded |
per-key requests/minute exceeded | yes, after Retry-After seconds |
| 429 | quota_exceeded |
monthly input-token allowance used up | no (until next month / upgrade); Retry-After = seconds to the next period |
| 500 | (detail) | inference error | yes, with backoff |
| 502/503/504 | — | transient (deploy, scaling) | yes, with backoff |
Rate limits and balance
Requests are limited per key to 300 requests/minute by default (custom limits on request), and spend is
bounded by your prepaid balance (no monthly quotas). At $0, calls return 402 insufficient_balance.
Limits are counted per calendar minute (UTC). Headers on successful responses:
| Header | |
|---|---|
x-ratelimit-limit |
requests/minute for this key |
x-ratelimit-remaining |
remaining in the current minute |
x-vana-input-tokens / x-vana-output-tokens |
tokens metered for this call |
x-vana-model |
resolved model id (vana-3.0) |
x-vana-balance |
remaining prepaid credit (USD, 6 decimals) after this call |
x-vana-low-balance |
true when the balance is under the low-balance threshold ($2 default) |
Retry-After |
on 429: seconds to wait |
The SDKs retry 429 (rate limit) and 5xx automatically with exponential backoff, honoring Retry-After.