API Errors and Limits

Every error code the API can answer, what it means, and the limits on requests and credits.

Open the tool

This page lists every error the Public API can answer and every limit on a key.

What it does

An error always has this shape, and the code never changes its meaning:

{ "error": { "code": "spend_cap_reached", "message": "...", "request_id": "...", "period": "day", "cap": 2000, "used": 1990, "need": 25 } }

Build your code on code, not on message. Quote request_id when you write to support.

When to use it

Read this page when a call fails, and before you put your code into use.

Every option explained

Limits

Limit	Value
Requests a minute	What you set on the key, up to 120
Spend a day and a month	What you set on the key, in Credits. Days and months run on India time.
Keys	Up to 10 on an account
Webhooks	Up to 3 on an account
Prompt	2,000 characters

A job that is failing or blocked stops counting against your cap, because it costs nothing. Your balance is always the last limit.

Errors

Code	Status	What to do
`invalid_request`	400	Check the fields. `reason` may name the one that is wrong.
`invalid_json`	400	The body is not valid JSON
`idempotency_key_required`	400	Add an `Idempotency-Key` header
`key_missing`	401	Add the `Authorization` header
`key_invalid`	401	Check the key
`key_revoked`	401	This key was revoked. Make a new one.
`key_expired`	401	This key has expired. Make a new one.
`insufficient_credits`	402	Top up. `need` and `have` say how much.
`spend_cap_reached`	402	Raise the cap on this key, or wait
`plan_required`	403	Change to a plan with the API
`api_closed`	403	The API is not open for this account
`scope_missing`	403	Add the scope named in `scope` to this key
`feature_closed`	403	This tool is not open for this account
`account_blocked`	403	Contact support
`email_unverified`	403	Verify your email on the website
`terms_not_accepted`	403	Accept the latest terms on the website
`age_required`	403	Confirm your age on the website
`not_found`	404	No such id on this account
`asset_not_found`	404	An asset id in the request is not on this account
`idempotency_conflict`	409	This key was used with another request. Use a new one.
`idempotency_in_progress`	409	The first call is still running. Wait and try again.
`content_blocked`	422	Stopped by the content rules. Nothing was charged.
`prompt_required`, `text_required`	422	Add the words
`text_too_long`	422	Shorten it to `max`
`ratio_not_supported`, `count_not_supported`, `seconds_not_supported`, `tier_not_supported`, `mode_not_supported`	422	Pick a value from this list
`too_many_references`, `reference_required`, `frame_not_supported`, `product_required`	422	Check the pictures in the request
`language_not_supported`, `voice_not_found`	422	Pick one from `GET /voices`
`upload_type`, `upload_size`, `upload_dimensions`, `upload_not_found`, `upload_blocked`	422	Check the file
`rights_required`, `consent_required`	422	Confirm the rights or the consent
`influencer_not_ready`, `presenter_not_ready`	422	Finish it on the website
`media_not_supported`	422	This tool does not take this kind of file
`limit_reached`	422	This account has reached a limit of this tool
`authorization_pending`, `slow_down`, `access_denied`, `expired_token`	400	See Connect an app
`rate_limited`	429	Wait for the seconds in `Retry-After`
`internal_error`	500	Our fault. Try again, and quote `request_id` if it stays.
`unavailable`	503	Paused for a moment. Try again shortly.

A job that ends badly has an error of its own: generation_failed, with its held credits sent back, content_blocked, or the code that stopped it before it started.

Common problems

I get rate_limited on a slow script

Your limit counts every call, including reading a job. Use a webhook in place of asking every second.

A call failed. Did it charge me?

No error charges you. To be sure, send the same call with the same Idempotency-Key: you get the job if there was one, and a new one if not.

Related guides

Updated 1 Nov 2026