Errors & Retries

Understand platform errors, upstream errors, streaming disconnects, and retry strategy.

HTTP errors

Error CodesSolution
400The request body, path, or parameter shape is invalid.
401Missing, malformed, expired, or disabled API key.
402The key or account does not have enough available balance or quota.
403The key is valid but cannot access the requested model.
429The request was throttled by OneRouter or by the upstream provider.
500Unexpected platform error. Retry with backoff if the operation is idempotent.
502The upstream provider returned an error or disconnected before completion.
503No usable upstream capacity was available for the selected model at that moment.

Platform vs upstream errors

OneRouter-owned errors use a platform error envelope. Upstream errors may be forwarded in the upstream provider's shape. Client code should read HTTP status first, then inspect the JSON error object defensively.

Retry guidance

Retry 429, 502, and 503 with exponential backoff when the operation is safe to repeat. Avoid blind retries for media generation or paid operations unless you use idempotency or can tolerate duplicate jobs. For streaming, a disconnected stream may have already consumed upstream resources.