Skip to main content

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​

TypeHTTP statusRetry?Meaning
invalid_request400noThe request is malformed or a parameter is invalid. Fix the request before retrying.
unsupported_parameter400noA parameter or parameter value is not supported by this endpoint or model.
context_length_exceeded400noThe input is longer than the model's context window. Shorten the input or pick another model.
invalid_callback_url400noThe callback / webhook URL is not an allowed public https URL.
content_policy400noThe input or output was refused by the content safety filters.
authentication_error401noMissing, invalid or expired credentials (API key, token, or second factor).
insufficient_quota402noThe account, organisation or API balance does not have enough credits for this request. Top up and retry.
key_limit_exceeded403noThe API key has reached its own spending limit. Raise the key limit or use another key.
permission_denied403noThe credentials are valid but not allowed to perform this action or access this resource.
plan_required403noThe feature or model needs a higher subscription plan.
not_found404noThe requested resource does not exist or is not visible to the caller.
model_not_found404noThe model does not exist, is not available to the caller, or has been retired.
conflict409noThe request conflicts with the current state of the resource (duplicate, already done, wrong state).
idempotency_conflict409noThe Idempotency-Key was already used with a different request body, or that request is still running.
job_not_ready409yesThe job has not finished yet, so its output is not available. Poll again later.
payload_too_large413noThe request body or an uploaded file is larger than the allowed size.
rate_limited429yesToo many requests in a short time. Back off and retry after the Retry-After interval.
quota_exceeded429noA plan or usage quota for the current period is used up. Retrying before it resets will not help.
cancelled499noThe request or job was cancelled before it completed.
internal_error500yesAn unexpected error on our side. Retry with backoff; contact support with the request_id if it persists.
provider_error502yesAn upstream provider (model host, payment processor, webhook endpoint) returned an error.
provider_unavailable503yesEvery upstream provider for this model is unavailable right now. Retry later or use another model.
model_unavailable503yesThe model exists but cannot serve requests right now (no active route). Retry later or use another model.
service_unavailable503yesA FunAI service or its database is temporarily unavailable. Retry with backoff.
timeout504yesThe 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​

SituationStatustypecodedetails
API balance too low402insufficient_quotainsufficient_api_balancebalance_usd, required_usd, top_up_url
Key spend cap reached403key_limit_exceededkey_spend_cap_exceededlimit_usd, spend_usd, resets_at, reset
Model not on the key's allow-list403permission_deniedmodel_not_allowed
Caller IP not on the key's allow-list403permission_deniedip_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-After when it is present.
  • Don't retry other errors without changing the request.
  • Send an Idempotency-Key on generation requests so a retry after a network timeout can't run the job twice. See Rate limits & idempotency.