Errors and retries

Errors can occur before a request is accepted or later during generation.

Synchronous errors

Most HTTP errors use the FastAPI error envelope:

{
  "detail": "Invalid credentials"
}

Validation errors may return a list in detail. Do not parse human-readable messages to make permanent business decisions.

Status	Typical meaning	Retry?
`400`	Invalid parameters, rejected input, or concurrency reached	After correcting the request or waiting
`401`	Missing or invalid credentials	No
`403`	Insufficient credits	After funding the account
`404`	Request or model not found for this account	No
`422`	Request body validation failed	No
`423`	Model is temporarily blocked	Later
`500`	Unexpected server error	Yes, with backoff
`503`	Model is disabled or not ready	Later

An accepted request can later finish with failed or nsfw:

{
  "status": "failed",
  "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff",
  "error": "Generation failed"
}

Failed and NSFW requests are not charged; any reserved credits are refunded.

Retry GET status requests after network failures and 5xx responses.
Do not retry authentication or validation failures without changing the request.
Use exponential backoff with jitter.
Set maximum attempts and a total retry deadline.
Do not automatically repeat a generation POST after an ambiguous timeout because submissions do not currently accept an idempotency key.

Every API response includes an X-Correlation-ID header. Record it with the request_id and include both when contacting support.