> This page is for version v2 (default).
> For other versions, use one of these documentation indexes:
> - v2 (default): https://developer.ideogram.ai/v2/llms.txt
> - v1: https://developer.ideogram.ai/v1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.ideogram.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.ideogram.ai/_mcp/server.

> Every Ideogram API error and outcome, whether it is billed, and what to do: safety rejections, unsafe images, failed generations, timeouts and access errors.

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

| Outcome                                                        | What you receive                                                           | Billed                             | What to do                                                                                                                                                                                         |
| -------------------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Price quote (`dry_run=true`)                                   | `200` with a `PriceQuote`                                                  | No                                 | See [Price quotes](/v2/ideogram-api/price-quotes)                                                                                                                                                  |
| Invalid request                                                | `400`                                                                      | No; the request doesn't run        | Fix the request using the endpoint's reference                                                                                                                                                     |
| Missing or invalid key                                         | `401`                                                                      | No; the request doesn't run        | Check the `Api-Key` header; see [Authentication](/v2/ideogram-api/authentication)                                                                                                                  |
| Not enough balance, or a plan limit                            | `402` with a `reject_reason` such as `insufficient_funds` or `daily_limit` | No; the request doesn't run        | Read `reject_reason`. For `insufficient_funds`, add credits or turn on auto recharge in **Wallet & Billing** in [Settings](https://ideogram.ai/platform). Retrying before that returns `402` again |
| No access to the endpoint, model or custom model               | `403`                                                                      | No; the request doesn't run        | Check that your organization has access. Contact [partnership@ideogram.ai](mailto:partnership@ideogram.ai) for access                                                                              |
| A source image, asset, custom model or generation wasn't found | `404`                                                                      | No; the request doesn't run        | Check the ID or file. The account endpoints also return `404` to a key without billing access; see [Authentication](/v2/ideogram-api/authentication#what-a-key-can-do)                             |
| An upload is too large                                         | `413` (Remove Objects and Ghost Mannequin)                                 | No; the request doesn't run        | Send a smaller file                                                                                                                                                                                |
| The prompt fails the safety check                              | `422`                                                                      | No                                 | Change the prompt. Describe also returns `422` when the image fails the check                                                                                                                      |
| Too many requests in flight                                    | `429` with `reject_reason: inflight_limit`                                 | No; the request doesn't run        | Wait, then retry; see [Rate limits](/v2/ideogram-api/rate-limits)                                                                                                                                  |
| An image fails the safety check                                | `200`, with `is_image_safe: false` and an empty `url` for that image       | Yes                                | Change the prompt or inputs before trying again                                                                                                                                                    |
| An asynchronous generation fails                               | `status: failed` and a `failure_reason` when you poll                      | No                                 | Read `failure_reason`, adjust and resubmit                                                                                                                                                         |
| A generation fails during a synchronous request                | `500`                                                                      | No                                 | Retry once. If it keeps failing, contact support                                                                                                                                                   |
| A synchronous request waits 265 seconds without finishing      | `503` with the error "The request took too long to finish"                 | Yes, when the generation completes | Send long jobs asynchronously. See [A timeout doesn't stop the work](#a-timeout-doesnt-stop-the-work)                                                                                              |
| The endpoint or model is temporarily unavailable               | `503` with an error that says so                                           | No; the request doesn't run        | Retry 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](/v2/ideogram-api/webhooks). 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](/v2/ideogram-api/idempotency).

## Error bodies

Rejections for account and usage limits use this shape:

```json
{
  "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

* `usage_cost_usd_micros` on a completed generation, when the request uses variable usage-based pricing
* [`GET /v2/account/usage`](/v2/api-reference/account/usage) for usage over a date range
* [`GET /v2/account/invoices`](/v2/api-reference/account/invoices) for invoices