Skip to main content
Core concepts

Errors and retries

Handle synchronous API errors and terminal generation failures.

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

#Synchronous errors

Most HTTP errors use the FastAPI error envelope:

json
{
  "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 or rejected input After correcting the request
401 Missing or invalid credentials No
403 Insufficient balance After adding funds
404 Request or model not found for this account No
409 The request is still running; for example, deleting a request that is queued or in_progress After it finishes
422 Request validation failed, an idempotency key was reused with different parameters, or Hf-Expires-After is out of range No
423 Model is temporarily blocked Later
429 The account's generation queue is full (account_queue_full) or an endpoint limit was reached; see Rate limits After Retry-After
500 Unexpected server error Yes, with backoff
503 Model is disabled or not ready, or queue admission is temporarily unavailable (admission_control_unavailable) Later, with backoff

#Terminal failures

An accepted request can later finish with failed or nsfw:

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

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

#Safe retry policy

  • 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.
  • Send an Idempotency-Key with every generation submission.
  • After an ambiguous timeout, network failure, or 5xx, repeat the same generation request with the same idempotency key.

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

Was this page helpful?
Navigation