> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mage.space/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and retries

> Every error the Mage API returns: the JSON envelope, each HTTP status and error code with its cause, how a failed request reports on a status read, and which calls are safe to retry.

Every error is a JSON envelope with a stable `code`, a `message` for a person, and sometimes more detail. Branch on the code, never on the message text.

```json theme={null}
{
  "error": {
    "code": "insufficient_gems",
    "message": "This generation costs 338 gems and the account balance is too low.",
    "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff",
    "gems_required": 338
  }
}
```

## Codes

| HTTP | Code | When | Retry |
| - | - | - | - |
| 400 | `invalid_request` | The body is not a JSON object, sets a server-owned field, names one setting twice, contradicts the endpoint's architecture, or the `Idempotency-Key` is malformed. | After fixing the request |
| 400 | `invalid_config` | A field has the wrong type or a value outside its tokens, an input could not be fetched, an `@handle` did not resolve or exceeds a budget, or a model rule was broken. The message names it. | After fixing the request |
| 401 | `unauthorized` | The key is missing, malformed, unknown, or revoked. | No |
| 402 | `insufficient_gems` | The balance is below the price. `gems_required` is the price. | After adding Gems |
| 402 | `payment_required` | The account has no successful payment yet. The API and the MCP server need one first: any Gem pack or plan. Signup bonus Gems work in the Mage app only. | After a first payment |
| 403 | `forbidden` | The account cannot generate. | No |
| 403 | `content_blocked` | The request was blocked by Mage's content policy before it ran. | No |
| 404 | `architecture_not_found` | No such architecture. The catalog lists the ids. | No |
| 404 | `request_not_found` | No request with this id belongs to the account, or it was not made through the API. | No |
| 404 | `character_not_found` | No character with this id belongs to the account. | No |
| 404 | `reference_not_found` | No reference with this id belongs to the account. | No |
| 404 | `not_found` | No such endpoint. `docs_url` points here. | No |
| 409 | `request_finished` | Cancel was called on a request that already completed or failed. | No |
| 409 | `handle_taken` | A create named a `handle` that a live character or reference already uses. `handle` is included. | With another handle, or without one |
| 410 | `architecture_retired` | The architecture was retired. | With another model |
| 429 | `too_many_requests` | The account has its cap of generations in flight. See [limits](https://docs.mage.space/api/limits.md). | After some finish, with backoff |
| 451 | `content_blocked` | The request was blocked by an external content restriction. | No |
| 500 | `internal_error` | Something failed on Mage's side. The failure is reported to Mage automatically. | Yes, with backoff and an idempotency key |

Codes are an open set: a new one may appear within a version. Treat a code you do not know by its HTTP status.

## Refusals that carry a request id

A submit that Mage records before refusing it (`402`, `403`, `410`, `429`, `451`, and a `400` or `500` raised by the run itself) carries `request_id` in the envelope. Its status read reports how the request ended, and its Gems ledger is visible in the app, even if you sent no idempotency key. The key you sent with it is spent: a retry with the same `Idempotency-Key` replays this failed request instead of submitting again. After fixing the cause, submit a new attempt with a new key.

## Failures on a status read

A request that was accepted and then failed reports `status: failed` with `error.code` set to one of these, and `billing` shows both the charge and the refund.

| Code | Meaning | Gems |
| - | - | - |
| `generation_failed` | The generation did not produce output. Most failures are transient; try again. | Refunded |
| `content_blocked` | Moderation forbade the output, or the model's provider refused the content. | Kept for forbidden output; refunded for a provider block |
| `preprocess_refused` | The source media could not be prepared for the model, so the run stopped before it generated. | Refunded |
| `insufficient_gems` | The balance was too low when the run started. | Never charged |

The text of a model's own error is never forwarded.

### Provider blocks

When the model's external provider refused the content, rather than Mage, `error` also carries `reason` and `stage`, so you can fix the request instead of guessing:

| `reason` | The provider refused | What to change |
| - | - | - |
| `likeness` | A real person or celebrity | Remove real people from the prompt and images |
| `ip` | Copyrighted or trademarked material | Describe an original design instead of a character, brand, artist, or lyrics |
| `nsfw` | Content past the model's own limit (sexual, violent, or otherwise sensitive) | Try another model, or soften the request |
| `minors` | Content that may involve a minor | Make sure everyone depicted is clearly an adult |
| `audio` | The audio, usually copyrighted music or a real person's voice | Remove music or voices from the inputs, or generate without audio |
| `unspecified` | Something it did not name | Reword the prompt or change the images |

`stage` is `input` when the provider refused the prompt or the input media, `output` when it refused the generated media, and `null` when it did not say. Retrying the same request usually gets the same block. New reasons may appear within a version; treat an unknown one as `unspecified`.

```json theme={null}
{
  "status": "failed",
  "error": {
    "code": "content_blocked",
    "message": "The model's provider refused a real person or celebrity in the prompt or images. Any gems charged were refunded.",
    "reason": "likeness",
    "stage": "input"
  }
}
```

## Retry policy

* Retry status reads on network errors and `5xx` responses, with exponential backoff and jitter.
* Retry a submit that got no response (a timeout or a network error) with the same [`Idempotency-Key`](https://docs.mage.space/api/requests#retrying-a-submit-safely), so it cannot charge twice.
* An error envelope that carries `request_id` has consumed its key: the refusal is recorded as that request, and the same key replays it. Fix the cause, then submit again with a new key.
* Do not retry `401`, `403`, `404`, `409`, or `451`, and do not retry a `400` without changing the request.
* Wait on `429` and on `402` until requests finish or Gems are added, then submit again, with a new key when the envelope carried `request_id`.
* Give every retry loop a cap on attempts and a deadline.

The [TypeScript](https://docs.mage.space/api/sdks/typescript.md#retries-and-idempotency) and [Python](https://docs.mage.space/api/sdks/python.md#retries-and-idempotency) SDKs follow this policy for you, and raise each envelope as an error with its `code`, `status`, and `request_id`.

If you contact [mage@mage.space](mailto:mage@mage.space) about a request, include its `request_id` and roughly when it happened.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.