Skip to main content
The AI Gateway’s errors look like your provider’s errors, so the SDK you use raises them the same way. What changes is that some errors now come from your organization’s own rules: a guardrail, a budget, a model nobody approved. Your application should tell those apart from a provider having a bad minute.

Decide by code

Read the code from the error body (see Errors for where each format puts it) and act on it: The OpenAI and Anthropic SDKs already retry a 429 or a 5xx twice by default, with backoff. Raise max_retries if you need more, and let everything else fail fast.

Example

With the Anthropic SDK the code is in error.body["error"]["type"]; with the Gemini SDK, in the error’s status.

Show people a helpful message

Guardrail messages name the guardrails that fired and never repeat the text that triggered them, so they are safe to log. They are written for the developer, not for the person using your application: show your own wording, as in the example.

Keep the reference

Every reply, error or not, carries x-request-id. Log it with every error. Support and your admins can find the request in the request log from it. To set your own reference, send x-request-id with the request.