Errors and retries

API errors use an OpenAI-compatible JSON shape where possible:

{
  "error": {
    "message": "A human-readable explanation",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_request"
  }
}

During MVP integration, clients should tolerate an additional request identifier or provider metadata and should not depend on exact message text.

Status	Meaning	Retry?
`400`	Invalid JSON, unsupported parameter, or request validation failure	No; correct the request.
`401`	Missing, malformed, revoked, or invalid API key	No; verify or rotate the key.
`402`	Account credit is depleted	No; add credit or contact the account owner.
`403`	Authenticated but not permitted for this resource or model	No; verify account access.
`413`	Request body is larger than the endpoint accepts	No; reduce the prompt or payload.
`429`	A rate or concurrency limit was reached	Yes; obey `Retry-After` when present.
`500`	Unexpected Corion application or gateway error	Usually; retry cautiously.
`502`	An upstream provider returned an unusable response	Usually; retry after backoff.
`503`	No provider capacity is currently available	Yes; retry after backoff.

Status mapping can vary while the public gateway contract is finalized. Clients should primarily branch on the HTTP status class and stable machine-readable error.code values once published.

Retry strategy

Retry 429, 500, 502, and 503 with exponential backoff and random jitter. Honor Retry-After; otherwise begin near one second and cap the delay. Use a small attempt limit and surface a failure rather than retrying indefinitely.

Do not automatically retry 400, 401, 402, 403, or 413. A retry without changing the request or account state is unlikely to succeed.

For non-streaming requests, send an application-level idempotency identifier if a future API revision documents one. The MVP does not yet guarantee idempotency for chat completions.

For streaming requests, preserve the partial response and ask the user before restarting when duplicate text would be harmful. A dropped stream does not prove the provider performed no work, and metered usage may still have occurred.