API error codes and how to fix them
Branch on the HTTP status and on data.code, never on the message text: codes are stable, messages are not.
Request errors
| Status | data.code | When | What to do |
|---|---|---|---|
| 401 | — | No credential, a malformed one, or a key or token that is unknown, revoked, or belongs to a suspended account. The response carries a WWW-Authenticate: Bearer challenge. | Send Authorization: Bearer sk-… (or x-api-key). Create a new key if this one was revoked. |
| 401 | key_expired | The key reached the expiry date chosen when it was created. | Rotate the key in Settings → API keys and deploy the new value. |
| 403 | ip_not_allowed | The key has an IP allow-list and this request came from an address outside it (or one that could not be resolved). | Call from an allowed address, or edit the key's allow-list. |
| 403 | insufficient_scope | The key or token lacks the scope this route needs; data.required names it. | Create a key with that scope, or re-authorize the OAuth client. |
| 403 | plan_required | The account's plan does not include API access, or the plan that did has lapsed. The key itself is kept. | Buy a plan or credit pack that includes API access; the same key starts working again. |
| 403 | — | The key's owner is no longer a member of the team the key bills. | Create a new key from an account that belongs to the team. |
| 403 | billing_account_unavailable | An OAuth connector (an AI assistant) was set to spend a team's credits, and its owner no longer belongs to that team. It does not fall back to personal credits. | Choose a billing account for the assistant in Settings → AI assistants, then retry. |
| 402 | insufficient_credits | The balance does not cover the generation. Nothing was charged and no workflow was created. | Top up credits, then resend the request. |
| 429 | key_credit_limit_reached | This API key has spent its monthly credit limit (UTC calendar month). The account may still hold credits; nothing was charged. data.limit, data.used and data.resetsAt say where it stands, and Retry-After counts the seconds to the reset. | Wait for the month to reset, or raise or clear the key's limit in API key settings. |
| 429 | connection_credit_limit_reached | An OAuth connector (an AI assistant) has spent the monthly credit limit its owner set for it (UTC calendar month). The account may still hold credits; nothing was charged. data.limit, data.used and data.resetsAt say where it stands. | Wait for the month to reset, or raise or clear the assistant's limit in Settings → AI assistants. |
| 400 | — | POST /v1/generate was sent without an Idempotency-Key header, or with one that is longer than the limit or contains characters outside printable ASCII. | Send a fresh UUID per generation and reuse it only on a retry. |
| 422 | — | The Idempotency-Key was already used for a DIFFERENT request body. | Use a new key for a new generation. The same key with the same body replays the original workflow. |
| 422 | — | The body names an unknown model or media type, or failed the model’s input validation (the message says which field). A few validation failures answer 400 instead. | Fix the named field. GET /v1/capabilities lists each model’s inputs. |
| 404 | — | The workflow id does not exist or belongs to another account, or the route does not exist. | Check the id returned by POST /v1/generate. |
| 429 | — | The per-key request limit was reached. The body is {"message":"too_many_requests","retryAfter":N}. | Wait for Retry-After seconds, then resend. |
| 429 | too_many_attempts | Too many requests with a REJECTED credential from this address; refused before the key is looked up. Successful requests never count. | Stop retrying the failing credential and read Retry-After; fix the key first. |
| 500 | — | The request failed on our side before a workflow was created. | Retry with the SAME Idempotency-Key, so a request that did go through is replayed rather than billed twice. |
Generation error codes
submit codes refuse the request before a workflow exists (data.code on the response). terminal codes end a workflow (data.workflow.errorCode on the poll). 6 further codes exist only for signed-out web visitors and never reach an API caller.
| Code | Phase | Retry? | Meaning |
|---|---|---|---|
content_policy_prompt | terminal | no | This request was declined by our content rules. Edit the description and try again. |
content_policy_input | terminal | no | This request was declined by our content rules. Adjust the description or the file you added, then try again. |
content_policy_output | terminal | yes | The result did not pass our content checks. Running it again usually produces a different result. |
output_quality_rejected | terminal | yes | The result came out with a defect our checks caught, so it was not delivered. Running it again usually produces a clean result. |
sequence_length_mismatch | terminal | yes | The cut came out a different length than planned, so it was not delivered. Running it again usually produces the right length. |
output_tone_changed | terminal | yes | The retouch changed the person's skin tone, so it was not delivered. Running it again usually keeps the tone. |
safety_check_unavailable | terminal | yes, after 30s | The safety check could not run just now. Please try again in a moment. |
request_invalid | terminal | no | One of the values in this request was not accepted. Review the fields and try again. |
input_unsupported | terminal | no | The selected model cannot work with this combination of inputs. |
input_media_unreadable | terminal | no | The uploaded file could not be read. Try a different file. |
input_length_mismatch | terminal | yes | The uploaded file measured a different length than your browser read, so nothing was made. Run it again to price it by the measured length. |
capacity_unavailable | terminal | yes, after 60s | Too many requests are running right now. Please try again shortly. |
timed_out | terminal | yes | This run took too long to finish. Please try again. |
generation_failed | terminal | yes | This run could not be completed. Trying again often works; if it keeps failing, change the request. |
output_delivery_failed | terminal | yes | The result was produced but could not be saved. Please try again. |
startup_failed | terminal | yes | This run could not be started. Please try again. |
canceled | terminal | yes | This run was canceled. |
unknown | terminal | yes | This run could not be completed. Please try again. |
insufficient_credits | submit | no | This generation costs more credits than the balance can cover. |
concurrency_limit | submit | yes, after 30s | The plan limit for simultaneous generations is reached. Wait for one to finish. |
model_unavailable | submit | no | This model is not available right now. Nothing was charged. Choose a different model. |
plan_required | submit | no | Your plan does not include this model or option. Nothing was charged. Choose a plan that includes it. |
price_changed | submit | yes | The price of this run changed since it was shown. Nothing was charged; check the new price and submit again. |
auth_required | submit | no | This needs a signed-in account. Sign in to continue. |
media_blocked | submit | no | This file can't be used. |
source_resolution_unsupported | submit | no | Only a video made at 720p can be extended. Nothing was charged. Choose a 720p video. |