Skip to content

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

Statusdata.codeWhenWhat 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.
401key_expiredThe key reached the expiry date chosen when it was created.Rotate the key in Settings → API keys and deploy the new value.
403ip_not_allowedThe 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.
403insufficient_scopeThe 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.
403plan_requiredThe 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.
403billing_account_unavailableAn 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.
402insufficient_creditsThe balance does not cover the generation. Nothing was charged and no workflow was created.Top up credits, then resend the request.
429key_credit_limit_reachedThis 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.
429connection_credit_limit_reachedAn 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.
429too_many_attemptsToo 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.

CodePhaseRetry?Meaning
content_policy_promptterminalnoThis request was declined by our content rules. Edit the description and try again.
content_policy_inputterminalnoThis request was declined by our content rules. Adjust the description or the file you added, then try again.
content_policy_outputterminalyesThe result did not pass our content checks. Running it again usually produces a different result.
output_quality_rejectedterminalyesThe result came out with a defect our checks caught, so it was not delivered. Running it again usually produces a clean result.
sequence_length_mismatchterminalyesThe cut came out a different length than planned, so it was not delivered. Running it again usually produces the right length.
output_tone_changedterminalyesThe retouch changed the person's skin tone, so it was not delivered. Running it again usually keeps the tone.
safety_check_unavailableterminalyes, after 30sThe safety check could not run just now. Please try again in a moment.
request_invalidterminalnoOne of the values in this request was not accepted. Review the fields and try again.
input_unsupportedterminalnoThe selected model cannot work with this combination of inputs.
input_media_unreadableterminalnoThe uploaded file could not be read. Try a different file.
input_length_mismatchterminalyesThe 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_unavailableterminalyes, after 60sToo many requests are running right now. Please try again shortly.
timed_outterminalyesThis run took too long to finish. Please try again.
generation_failedterminalyesThis run could not be completed. Trying again often works; if it keeps failing, change the request.
output_delivery_failedterminalyesThe result was produced but could not be saved. Please try again.
startup_failedterminalyesThis run could not be started. Please try again.
canceledterminalyesThis run was canceled.
unknownterminalyesThis run could not be completed. Please try again.
insufficient_creditssubmitnoThis generation costs more credits than the balance can cover.
concurrency_limitsubmityes, after 30sThe plan limit for simultaneous generations is reached. Wait for one to finish.
model_unavailablesubmitnoThis model is not available right now. Nothing was charged. Choose a different model.
plan_requiredsubmitnoYour plan does not include this model or option. Nothing was charged. Choose a plan that includes it.
price_changedsubmityesThe price of this run changed since it was shown. Nothing was charged; check the new price and submit again.
auth_requiredsubmitnoThis needs a signed-in account. Sign in to continue.
media_blockedsubmitnoThis file can't be used.
source_resolution_unsupportedsubmitnoOnly a video made at 720p can be extended. Nothing was charged. Choose a 720p video.