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
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, carriesx-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.