Errors and retries

Production integrations should distinguish request, authentication, authorization, quota, routing, and upstream failures.

Categories

Type	Common status	Direction
Invalid request	400, 413	Inspect payload, size, fields, and model support
Authentication	401	Check key and headers
Authorization	403	Check key status, model/IP/group/routing policy
Path mismatch	404	Check Base URL and client path concatenation
Rate or quota	429	Reduce concurrency and inspect quota/upstream throttling
Temporary failure	5xx	Use bounded backoff and inspect logs

Backoff

For 429 and selected transient 5xx responses, exponential backoff with jitter is usually appropriate:

1s -> 2s -> 4s -> 8s

Always cap the number of attempts.

Billable generation requests

A network failure can happen after an upstream has accepted the request but before your client receives the response.

For that reason:

• do not blindly replay every POST,
• use bounded retries,
• review logs for expensive jobs,
• preserve asynchronous task IDs,
• implement application-level deduplication when the workflow allows it.

Timeouts

Separate connection timeout, first-byte timeout, and overall task duration. Long reasoning and media generation can require very different timeout budgets from short text calls.