Errors
Check the HTTP status and response body. Gateway errors and native provider errors can have different shapes.
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 the endpoint, model, selected pool, HTTP status, error type and request ID. Remove API keys, account codes, prompts and private response content.
Questions about your integration? support@zrelay.net