Errors, Limits, and Retries

Gateway errors follow the response shape of the client protocol you use. Every business response includes x-request-id; keep it when investigating a failure or contacting support.

Common HTTP statuses

402 is decided by the request's maximum possible cost (input plus the output allowed by max_tokens), so it can appear before your balance reaches zero. When some balance remains, the error message suggests lowering max_tokens (or your protocol's equivalent output limit); retry with a smaller value to use up the remaining balance.

Check request logs for the stable error code, selected model, status, and timing information.

Retry safely

Retry read-only task queries with bounded exponential backoff. Do not automatically retry a model-creation POST when the client cannot tell whether the server accepted it; doing so can create duplicate billable work. Incoming model requests do not support Idempotency-Key.

For streaming calls, preserve already received output and distinguish a clean completion from a disconnected or truncated stream.