# Errors

Check the HTTP status and response body. Gateway errors and native provider errors can have different shapes.

Source: https://zrelay.net/docs/api/errors/

## HTTP status codes

| Status | Action |
| --- | --- |
| 400 | Check JSON, endpoint, parameters and token limits |
| 401 / 403 | Check the key, authentication header and model permission |
| 402 | Check balance, key spending cap or trial allowance |
| 422 | Choose a model available in the key’s selected pool |
| 429 | Wait; respect Retry-After when present |
| 502 / 503 | Temporary gateway or upstream failure; use bounded, safe retries |
| 503 · Authorization service unavailable | Zrelay could not complete internal authorization for this request. If the error persists, send support the time with its time zone and the request ID or TraceID. |

## Error body

```
{
  "error": {
    "type": "invalid_request_error",
    "message": "Example validation error"
  }
}
```

This is an illustrative gateway shape. Provider errors may retain the native endpoint format; do not assume every failure contains exactly these fields.

## Retry safely

Do not retry invalid credentials, invalid bodies or exhausted balance in a loop. Use bounded backoff for temporary failures. If a stream or tool execution already started, inspect the outcome and billing before repeating work; cancelling a request does not prove that it had no effect or charge.

## Report a problem

Send [support@zrelay.net](mailto:support@zrelay.net) the endpoint, model, selected pool, HTTP status, error type and request ID. Remove API keys, account codes, prompts and private response content.