Errors and retries

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.

{
  "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, 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, 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
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	`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
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.	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 lab blocked it.	Kept for forbidden output; refunded for a lab block
`insufficient_gems`	The balance was too low when the run started.	Never charged

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

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, 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.

If you contact mage@mage.space about a request, include its request_id and roughly when it happened.

Get started

Concepts

Endpoints

Models

Image models

Video models

Errors and retries

Codes

Refusals that carry a request id

Failures on a status read

Retry policy

​Codes

​Refusals that carry a request id

​Failures on a status read

​Retry policy

Codes

Refusals that carry a request id

Failures on a status read

Retry policy