REST API

Errors and retries

Handle consistent JSON errors, retry only safe failures, and understand when generation credits are refunded.

Error shape

Non-2xx REST responses use one predictable JSON envelope.

Error response

{
  "error": {
    "code": "validation_error",
    "message": "Input validation failed",
    "details": { "field": "duration" }
  }
}

Error codes

Status	Code	Meaning
400	validation_error	The request or model input is invalid; the message names the field.
401	unauthorized	The API key is missing, invalid, or revoked.
402	insufficient_credits	Top up the shared account balance and retry.
404	not_found	The model or owned generation does not exist.
409	idempotency_conflict	The idempotency key was already used with another payload.
429	rate_limited	Respect the Retry-After header before retrying.
5xx	internal_error	The failure happened on our side; failed dispatches follow the refund path.

Retry policy

400, 401, 402, 404Do not retry unchangedCorrect the request, key, balance, or resource ID.

409Inspect idempotency keyReuse only with the original payload or create a new logical job.

429Retry laterWait for Retry-After, then continue with backoff.

5xxRetry with idempotencyUse bounded exponential backoff and the same idempotency key.

Refund behavior

Validation and authentication errors do not create a paid generation. If credits were reserved and provider dispatch then fails, the generation's existing refund path restores those credits. Check the job status or the Developer API usage screen before issuing another logical request.