Error format

When anything under /api/v1/** fails, the HTTP status is not 2xx and the body always has the same shape:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key does not have the generate:write permission.",
    "request_id": "req_xxxxxxxxxxxxxxxxxxxx"
  }
}

Field	Description
`code`	Machine-readable error code. Branch on it. Stable, never changes
`message`	Human-readable explanation. It follows the language: the website uses the interface language, the API uses `Accept-Language`, and the default is Chinese. May change; don't match on it
`request_id`	Unique id of this request, identical to the `X-Request-Id` response header and the Developer Center logs. Include it when reporting a problem

Successful responses carry the X-Request-Id header too.

GET /api/file/<filename> is not under /api/v1 and returns plain-text errors, see image download.

Status codes

Status	`code`	Meaning	What to do
`400`	`invalid_request` and sub-codes	Invalid parameters	Fix the parameters; don't retry
`401`	`unauthorized`	No `Authorization` header	Add it
`401`	`invalid_api_key`	Key invalid, revoked or expired; `message` says which	Create a new key
`402`	`insufficient_credits`	Not enough credits; `message` states how much is needed and how to top up	Top up
`403`	`insufficient_scope`	Key lacks the required scope	Create a key with that scope
`403`	`banned`	Account banned	Contact support
`404`	`session_not_found`	`session_id` doesn't exist or isn't yours	Omit it, or pass one of your own
`404`	`not_found`	Image pack publication doesn't exist or isn't yours	—
`429`	`rate_limited`	Key over its 24-hour limit	Wait for the window to pass, see rate limits
`429`	`new_user_daily_limit`	New account over its 24-hour spend cap	Come back tomorrow
`500`	`internal_error`	Generation failed or server error. Reserved credits have been refunded	Retry once; if it keeps failing, report with `request_id`
`503`	`auth_unavailable`	Authentication service temporarily unavailable	Retry in a few seconds

400 sub-codes

Parameter errors on POST /api/v1/generate come with a specific sub-code:

`code`	Meaning
`invalid_request`	Body is not JSON, or both `prompt` and `ref_image_ids` are missing
`prompt_too_long`	`prompt` exceeds 4000 characters
`invalid_model`	`model` is not in the model table
`invalid_ratio`	`ratio` is invalid, or unsupported by this model; `message` lists the allowed values
`invalid_resolution`	`resolution` is not `1K` / `2K` / `4K`
`invalid_quality`	`quality` is not `low` / `medium` / `high`
`invalid_image_count`	`n` is not 1 / 2 / 4
`invalid_reference_images`	`ref_image_ids` is not an array of strings
`too_many_reference_images`	More reference images than the model allows
`reference_image_missing`	A reference image is no longer in the Library (deleted or cleaned up)
`prompt_or_reference_required`	Prompt and reference images can't both be empty

Retry advice

400 / 401 / 402 / 403 / 404: retrying gives the same answer. Fix the request first
429 rate_limited: 24-hour rolling window. Back off exponentially; never retry immediately
500: credits are refunded, so retry once as-is. If it keeps failing, stop and report with request_id
503: retry after a few seconds
Network timeout: generation can take up to 5 minutes. After a timeout, don't blindly resend. Check "Recent conversations" on the website first to see whether that run produced images, so you don't pay twice

Status codes

400 sub-codes

Retry advice

Table of Contents