Errors

The error body

Errors from the inference API use OpenAI's shape:

{
  "error": {
    "message": "Not enough credit for this request. Add credit in the Console, or lower max_tokens.",
    "type": "insufficient_quota",
    "code": "insufficient_credit",
    "param": null
  }
}

• code is the field to branch on. It is stable; the message wording may change.
• type follows the status: invalid_request_error for 400, 404 and 413, authentication_error for 401, insufficient_quota for 402, permission_error for 403, rate_limit_error for 429, and api_error for 5xx.
• param names the offending field when there is one, such as model or messages[0].content.
• Messages are written by Safeguard. A provider's own error text is never copied into them; a provider failure is described by its HTTP status only.
• An error returned after the gateway accepted the request and called a provider also carries an X-Generation-Id header with the request's id (gen-…), because the request is in the request log. A refusal before that, such as a 401, 402 or 429 rate_limited, has no request id. X-Request-Id is a different, internal id for Safeguard's audit trail.

The OpenAI SDKs turn these into their usual exceptions, with the status code and this body.

Every status and code

Two answers do not use this body, because they come from the API's router before the gateway's code runs: a path the API does not serve, such as /embeddings, returns 404 with {"detail": "Not Found"}, and a wrong method, such as GET /chat/completions, returns 405 with {"detail": "Method Not Allowed"}.

The messages you will see most

Retry-After

Two errors carry a Retry-After header, in whole seconds:

• 429 rate_limited: the time until your oldest counted request leaves the 60-second window. A refused request is not counted, so a retry after that wait goes through.
• 429 upstream_rate_limited: always 5.

The order of the checks

The gateway checks a request in this order and answers with the first problem it finds:

1. The key (401), then whether the API Platform is on for the workspace (403).
2. The body: size (413) and fields (400).
3. The key's requests per minute (429 rate_limited).
4. The model: known (404) and callable (503).
5. Credit and spend limits for the most the request could cost (402).
6. The provider call (400 upstream_rejected, 429 upstream_rate_limited, 502, 504).

A request refused at steps 1 to 5 never reaches a provider and costs nothing.

Errors during a stream

Once a stream has started, the status is already 200, so a failure arrives as an event in the stream instead:

data: {"error": {"message": "The provider stream ended with an error.", "type": "api_error", "code": "upstream_error", "param": null}}

It is followed by the usage chunk, if you asked for one, and data: [DONE]. See Streaming.

How to retry

• Retry 429 after Retry-After. Retry 500, 502, 503 auth_unavailable, 503 billing_unavailable and 504 with exponential backoff and a cap on attempts.
• Do not retry the other 4xx errors unchanged; they will fail the same way.
• Each retry is a new request with a new request id. A retry that reaches a provider and gets an answer is billed like any other request.
• When your workspace or request allows fallbacks, the gateway already retries a failed provider call once before it answers with an error. See Reliability and fallbacks.

Troubleshooting walks through the common cases and their fixes.