Developers
Errors & rate limits
Error format, every error code the API returns, what to do about each, and the per-key rate limit.
On this page
Errors use the familiar JSON shape. The OpenAI SDKs turn them into their usual error classes (APIError, AuthenticationError, RateLimitError, …).
{ "error": { "code": "spend_limit_reached", "message": "This API key reached its monthly spend limit", "monthlyLimitMicro": 5000000, "spentThisPeriodMicro": 5000000, "periodResetsAt": "2026-11-01T00:00:00.000Z" } }
Branch on error.code, not on the message. Amounts ending in Micro are in micro-USD: 1,000,000 equals $1.
| HTTP | code | What to do |
|---|---|---|
| 400 | invalid_request | Fix the request. message names the field. |
| 400 | upstream_rejected | The model rejected the input, e.g. it's longer than the context window. |
| 401 | invalid_api_key | The key is wrong or revoked. Create a new one. |
| 402 | insufficient_credits | Free credits plus paid balance can't cover the request. Lower max_tokens, pick a different model, or top up. resetsAt says when free credits refill. |
| 402 | spend_limit_reached | The key hit its monthly limit. Raise it on the Developers page, or wait for periodResetsAt. |
| 403 | tee_api_not_available | TEE through the API isn't available yet. Use mode: "anonymous". |
| 404 | model_not_found | Unknown model id. Check GET /v1/models. |
| 404 | model_unavailable | The model can't answer right now. Try another one or add fallback_models. You were not charged. |
| 404 | not_found | Unknown or expired video job or media link. |
| 409 | request_in_progress | An image request with the same X-Tacita-Request-Id is still running. Poll GET /media/by-request/{id}. |
| 413 | payload_too_large | The body is over 4 MB. |
| 422 | content_blocked | The image or video prompt was refused by the safety check. |
| 429 | rate_limited | Slow down. Respect Retry-After. |
| 502 | upstream_error | The provider failed. Retry. You were not charged. |
| 503 | upstream_unavailable, upstream_rate_limited | Temporary. Retry with backoff. You were not charged. |
| 503 | moderation_unavailable | The image and video safety check is down. Retry shortly. |
| 503 | media_unavailable | The image could not be stored for delivery. You were not charged. Retry. |
| 500 | internal_error | Our bug. Retry, and tell us if it persists. |
Rate limits#
- 120 requests per minute per API key, the same for every key.
- Over the limit, you get
429 rate_limitedwithRetry-Afterin seconds. - The OpenAI SDKs retry 429 and 5xx automatically, twice by default.
Retries and charges#
- A failed request is never charged.
- If the stream fails after it started, you pay only for what was generated.
- Retrying is safe. A retry is a new request and is charged on its own.