Core concepts

Errors

A refused request gets a 4xx or 5xx status and a body with the same shape on every route.

json
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "A request parameter is missing or invalid. See 'param'.",
    "param": "limit"
  },
  "request_id": "req_8fK2mQ4vTn7cX1bZ9wLp3hRs"
}

Field	Description
`error.type`	Error family, derived from the status.
`error.code`	Precise and stable reason: the field to read in code.
`error.message`	English explanation, for the developer. Not to be shown to end users.
`error.param`	Parameter or header at fault (`image`, `layers[0].action`, `Idempotency-Key`…), or `null`.
`request_id`	Request identifier, identical to the `request-id` header.

Statuses

Status	`type`
400, 404, 405, 409, 413, 415, 422	`invalid_request_error`
401	`authentication_error`
402	`billing_error`
403	`permission_error`
429	`rate_limit_error`
500, 503	`api_error`

Codes

Status	Code	Cause
400	`parameter_invalid`	Missing or invalid parameter, header or JSON body; `param` names it.
400	`request_invalid`	Request refused with no more precise reason, a malformed `multipart/form-data` form for example.
400	`image_unreadable`	Unreadable image (see Input images).
400	`image_dimensions_invalid`	Image over 8,192 pixels per side or 36 million pixels; upscaling: see Upscaling.
400	`image_url_unreachable`	Image cannot be downloaded: private or unreachable URL, error response, timeout.
400	`mask_invalid`	Edit mask that is not a readable PNG.
400	`mask_dimensions_mismatch`	Mask with proportions different from the image, or a long side under 512 pixels (or the image's, if smaller).
400	`mask_colors_mismatch`	Mask colors and layers do not match; `param` names the layer or `mask`.
401	`api_key_missing`	`Authorization: Bearer …` header missing.
401	`api_key_invalid`	Malformed, unknown or revoked key, or deleted organization.
401	`api_key_expired`	Expired key.
402	`insufficient_balance`	Balance too low for the generation's price (see Billing).
402	`spend_limit_reached`	The generation would exceed the monthly limit.
403	`permission_denied`	Missing permission; the message names it (see Authentication).
403	`ip_not_allowed`	IP address not in the key's list.
403	`origin_not_allowed`	Request to `/mcp` sent from a web page (`Origin` header).
403	`organization_suspended`	Suspended organization, whatever the key. Contact support.
404	`route_not_found`	Unknown path under `/v1`.
404	`resource_not_found`	Resource that does not exist, belongs to another organization or to the other mode (test or live).
405	`method_not_allowed`	Method not allowed; the `Allow` header lists the allowed methods.
409	`conflict`	The request conflicts with the current state of the resource.
409	`generation_not_cancelable`	Generation already started or ended.
409	`idempotency_key_reused`	`Idempotency-Key` already used for another request (see Idempotency).
409	`idempotency_key_in_use`	A request with the same `Idempotency-Key` is still in progress.
413	`request_too_large`	JSON body over 64 KB; in `multipart/form-data`, over 64 KB of text fields or a body beyond five 10 MB images.
413	`image_too_large`	Image over 10 MB.
415	`unsupported_media_type`	Body neither in `application/json`, nor in `multipart/form-data` for a generation creation.
415	`unsupported_image_type`	Image that is not a JPEG, PNG or WebP by its content, or URL that does not return an image.
422	`content_policy_violation`	Edit instruction refused by moderation (`param` is `prompt`).
429	`rate_limit_exceeded`	Too many requests per minute (see Rate limits).
429	`generation_rate_limit_exceeded`	Generations launched per minute or per hour allowed by the tier reached (see Rate limits).
500	`internal_error`	Internal error.
503	`maintenance`	API under maintenance.
503	`mode_unavailable`	This generation type is temporarily unavailable.
503	`service_unavailable`	Service temporarily unavailable (instruction moderation, transient outage).
503	`overloaded`	Heavy load: generation refused at admission, or received images not analyzed in time.

A generation request refused (4xx or 503) creates nothing and charges nothing.
A resource of another organization responds 404, never 403.
An accepted generation that fails later is not an HTTP error: its status is failed (see Generations).

Handling

429 and 503: retry after the number of seconds in the Retry-After header, or later if it is missing.
409 idempotency_key_in_use: retry later with the same idempotency key.
500: a few attempts at most, doubling the wait (1 s, 2 s, 4 s).
Other 4xx: fix the request; resent as is, it gets the same response.
Unknown code: handle it from its status and its type; new codes can be added.
Log the request-id header, present on every response: support uses it to find the call.