Errors
Errors come back with a non-2xx HTTP status and a JSON body. Every error has a
stable public type: branch on it (or on the HTTP status). The code is more
specific and is what support needs.
Error body
OpenAI-compatible endpoints (/v1/…) use the OpenAI error shape, so OpenAI SDKs
raise their usual exceptions:
{
"error": {
"message": "Your API balance is too low for this request.",
"type": "insufficient_quota",
"code": "insufficient_api_balance",
"param": null,
"request_id": "95022a77-2a56-4553-be06-a6a5aefcf0f1"
}
}
All other endpoints use the platform envelope:
{
"success": false,
"error": {
"code": "GATEWAY_13006",
"error_type": "authentication_error",
"message": "Authentication required. Provide Authorization (Bearer token) or X-API-Key header",
"details": {}
},
"meta": {
"timestamp": "2026-11-12T19:00:10.686863+00:00",
"request_id": "95022a77-2a56-4553-be06-a6a5aefcf0f1"
}
}
type/error_type: one of the types below. Stable; safe to branch on.code: the specific error. See Error codes.message: for people. Wording can change; don't parse it.request_id: quote it when you contact support.
If a stream has already started ("stream": true), an error arrives as one final
event data: {"error": {…}} followed by data: [DONE].
Error types
| Type | HTTP status | Retry? | Meaning |
|---|---|---|---|
invalid_request | 400 | no | The request is malformed or a parameter is invalid. Fix the request before retrying. |
unsupported_parameter | 400 | no | A parameter or parameter value is not supported by this endpoint or model. |
context_length_exceeded | 400 | no | The input is longer than the model's context window. Shorten the input or pick another model. |
invalid_callback_url | 400 | no | The callback / webhook URL is not an allowed public https URL. |
content_policy | 400 | no | The input or output was refused by the content safety filters. |
authentication_error | 401 | no | Missing, invalid or expired credentials (API key, token, or second factor). |
insufficient_quota | 402 | no | The account, organisation or API balance does not have enough credits for this request. Top up and retry. |
key_limit_exceeded | 403 | no | The API key has reached its own spending limit. Raise the key limit or use another key. |
permission_denied | 403 | no | The credentials are valid but not allowed to perform this action or access this resource. |
plan_required | 403 | no | The feature or model needs a higher subscription plan. |
not_found | 404 | no | The requested resource does not exist or is not visible to the caller. |
model_not_found | 404 | no | The model does not exist, is not available to the caller, or has been retired. |
conflict | 409 | no | The request conflicts with the current state of the resource (duplicate, already done, wrong state). |
idempotency_conflict | 409 | no | The Idempotency-Key was already used with a different request body, or that request is still running. |
job_not_ready | 409 | yes | The job has not finished yet, so its output is not available. Poll again later. |
payload_too_large | 413 | no | The request body or an uploaded file is larger than the allowed size. |
rate_limited | 429 | yes | Too many requests in a short time. Back off and retry after the Retry-After interval. |
quota_exceeded | 429 | no | A plan or usage quota for the current period is used up. Retrying before it resets will not help. |
cancelled | 499 | no | The request or job was cancelled before it completed. |
internal_error | 500 | yes | An unexpected error on our side. Retry with backoff; contact support with the request_id if it persists. |
provider_error | 502 | yes | An upstream provider (model host, payment processor, webhook endpoint) returned an error. |
provider_unavailable | 503 | yes | Every upstream provider for this model is unavailable right now. Retry later or use another model. |
model_unavailable | 503 | yes | The model exists but cannot serve requests right now (no active route). Retry later or use another model. |
service_unavailable | 503 | yes | A FunAI service or its database is temporarily unavailable. Retry with backoff. |
timeout | 504 | yes | The request or the upstream provider took too long to answer. Retry, or use an async job. |
The HTTP status is authoritative: when one code is sent with a different status, the type follows the status.
Balance and key limits
| Situation | Status | type | code | details |
|---|---|---|---|---|
| API balance too low | 402 | insufficient_quota | insufficient_api_balance | balance_usd, required_usd, top_up_url |
| Key spend cap reached | 403 | key_limit_exceeded | key_spend_cap_exceeded | limit_usd, spend_usd, resets_at, reset |
| Model not on the key's allow-list | 403 | permission_denied | model_not_allowed | |
| Caller IP not on the key's allow-list | 403 | permission_denied | ip_not_allowed |
Failed jobs
An async job can also end with "status": "FAILED". Its error_code uses the same
codes, for example GENERATION_2018 when a safety filter refused the prompt, input
or result. Change the prompt or input before trying again.
Retrying safely
- Retry only types marked retryable, with exponential backoff, and honour
Retry-Afterwhen it is present. - Don't retry other errors without changing the request.
- Send an
Idempotency-Keyon generation requests so a retry after a network timeout can't run the job twice. See Rate limits & idempotency.