Errors & idempotency

Recover safely without duplicating generations or charges.

API preview: generation providers are not connected. An authenticated request can return 503 without creating a task or charging credits.

Handle the cause, not just HTTP status

Category	What to do
Authentication / permission	Check your key and model scope. Do not automatically retry.
Invalid input / unsupported capability	Correct the input. Never silently remove fields.
Insufficient credits / cap too low	Review quantity, fallback, and the quote before a new submission.
Provider not configured	Expected for preview models. No real successful output is available.
Upstream result unknown	Keep the task ID and query; do not recreate the task.
Rate limit	Respect Retry-After and use bounded backoff.

One operation, one idempotency key

Use one stable Idempotency-Key for recovery of a particular request. The fingerprint includes model, normalized input, output_count, fallback, and max_credits. The same key with different business input is a conflict.

Idempotency keys are not API credentials. They prevent duplicate business acceptance, not unauthorized access. A user-requested regeneration is a new operation with a new key.

Give support a traceable ID

Keep request_id, task_id, item_id, timestamp, and a sanitized error. Never send full API keys or provider credentials. Logs show the operation, each result item, its attempts, and the credit outcome.

Open logs Get help