Errors & rate limits
Errors use OpenAI's shape, so SDKs raise them the way they raise OpenAI's. Every response carries an x-request-id.
| status | code | meaning |
|---|---|---|
| 400 | invalid_request | the body is wrong; param names the field |
| 400 | unsupported_parameter | this model doesn't take that parameter; the model's page lists the ones it does |
| 400 | invalid_buyback_token | x402 only: the X-Buyback-Token is not a mint, or not eligible for buybacks |
| 400 | x402_unsupported_model | x402 only: this model's price isn't known until it runs; use a key |
| 401 | missing_api_key | no key sent; send it as Authorization: Bearer <key> |
| 401 | invalid_api_key | wrong or revoked key |
| 402 | insufficient_balance | add funds, or pay this request with x402 |
| 402 | spending_cap_reached | a signed-in app hit its monthly cap; raise it under Connected apps |
| 404 | model_not_found | unknown or unlisted model id |
| 410 | media_expired / upload_expired | the file was deleted after 24 hours; generate or upload it again |
| 413 | payload_too_large | the request body is too large |
| 429 | rate_limit_exceeded | over the rate limit of 600 requests per minute per key; wait for Retry-After |
| 500 | internal_error | our error; retry, and quote the x-request-id if it repeats |
| 502 | generation_failed | the model failed to make the file; try again |
| 503 | no_capacity | no capacity for this model right now; wait for Retry-After |
| 504 | timeout | the model took too long; try again |
error body
{
"error": {
"message": "Your balance is too low for this request. Add funds to continue.",
"type": "insufficient_quota",
"code": "insufficient_balance",
"param": null
},
"request_id": "7f3c..."
}We retry a failed upstream attempt for you once before the first byte of a response; a stream that has started is never switched mid-way, and media generations are never retried. Quote the x-request-id when you contact us.