Skip to navigation

Errors and Billing

A request that Ideogram rejects before it runs is not billed. A request that runs is billed when it completes, including when an image is withheld by the safety check. A generation that fails is not billed. Ideogram doesn’t automatically refund a completed request.

Outcomes and billing

OutcomeWhat you receiveBilledWhat to do
Price quote (dry_run=true)200 with a PriceQuoteNoSee Price quotes
Invalid request400No; the request doesn’t runFix the request using the endpoint’s reference
Missing or invalid key401No; the request doesn’t runCheck the Api-Key header; see Authentication
Not enough balance, or a plan limit402 with a reject_reason such as insufficient_funds or daily_limitNo; the request doesn’t runRead reject_reason. For insufficient_funds, add credits or turn on auto recharge in Wallet & Billing in Settings. Retrying before that returns 402 again
No access to the endpoint, model or custom model403No; the request doesn’t runCheck that your organization has access. Contact partnership@ideogram.ai for access
A source image, asset, custom model or generation wasn’t found404No; the request doesn’t runCheck the ID or file. The account endpoints also return 404 to a key without billing access; see Authentication
An upload is too large413 (Remove Objects and Ghost Mannequin)No; the request doesn’t runSend a smaller file
The prompt fails the safety check422NoChange the prompt. Describe also returns 422 when the image fails the check
Too many requests in flight429 with reject_reason: inflight_limitNo; the request doesn’t runWait, then retry; see Rate limits
An image fails the safety check200, with is_image_safe: false and an empty url for that imageYesChange the prompt or inputs before trying again
An asynchronous generation failsstatus: failed and a failure_reason when you pollNoRead failure_reason, adjust and resubmit
A generation fails during a synchronous request500NoRetry once. If it keeps failing, contact support
A synchronous request waits 265 seconds without finishing503 with the error “The request took too long to finish”Yes, when the generation completesSend long jobs asynchronously. See A timeout doesn’t stop the work
The endpoint or model is temporarily unavailable503 with an error that says soNo; the request doesn’t runRetry later

The 422 row applies to v2 endpoints, which check the prompt before the request runs.

A timeout doesn’t stop the work

A synchronous request waits up to 265 seconds for its result. When the wait runs out, the request returns 503, but only your wait ends: the generation keeps running and is billed when it completes. The 503 response has no generation_id, so you can’t poll for that result, and sending the request again starts a second, separately billed generation.

For anything that can take long, send the request asynchronously (async or a webhook_url), record the generation_id, and poll or use a webhook. A 503 whose error says the endpoint or model is temporarily unavailable is different: nothing ran, so you can retry it. See Idempotency and safe retries.

Error bodies

Rejections for account and usage limits use this shape:

{
"error": "<message>",
"reject_reason": "insufficient_funds"
}

Read reject_reason rather than the error text, which is written for people and can change.

Check what you were charged