Errors

Errors are returned in your ingress format’s native error shape with the correct HTTP status code. Upstream provider failures are mapped to a stable taxonomy — the code values below never change meaning, so you can switch models and providers without rewriting error handling.

Error envelopes per format

{
  "error": {
    "message": "Workspace balance is not positive. Top up to resume.",
    "type": "insufficient_credits",
    "code": "insufficient_credits",
    "param": null
  }
}

{
  "type": "error",
  "error": {
    "type": "insufficient_credits",
    "message": "Workspace balance is not positive. Top up to resume."
  }
}

The taxonomy

This table is rendered from the gateway’s own error constants (@hyperinfer/shared), so it cannot drift from the implementation:

Handling guidance

• Retry with backoff: provider_rate_limit, provider_overloaded, provider_timeout, provider_unavailable, rate_limit_exceeded, internal_error. Honor the Retry-After header when present.
• Fix the request: invalid_request, context_length_exceeded, payload_too_large, model_not_allowed.
• Fix the account: insufficient_credits (top up), key_limit_exceeded (wait for the reset or raise the limit), invalid_api_key (rotate the key), workspace_locked (contact support).

The gateway itself retries upstream connect failures and pre-stream 5xx/429s at most twice with jittered backoff — and never retries once a response has started streaming, so you will never receive duplicated content.