Errors
The gateway error contract — status codes, error codes, and how to handle each one.
Every error from the gateway follows the same shape, so you can write one handler instead of one per endpoint.
{
"error": {
"code": "policy_violation",
"message": "Request blocked by guardrail",
"blocked_by": "geo_block",
"action": "reject",
"docs_url": "https://developers.relixr.com/docs/errors",
"dashboard_fix": "/dashboard/guardrails"
}
}Status Codes
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | invalid_request | Malformed JSON or missing required fields. | Fix the body; see Chat completions. |
| 401 | unauthorized | Missing/invalid key, or wrong key type (management vs inference). | Use an rlx_ inference key. |
| 402 | insufficient_balance | Reserve would exceed workspace balance. | Top up; or lower max_tokens. |
| 403 | policy_violation | Guardrail blocked the request — see blocked_by. | Adjust content or guardrails. |
| 404 | model_not_found | Model id not in catalog / not allowlisted. | Check /models and key allowlist. |
| 429 | rate_limited | Key or workspace rate limit. | Back off and retry. |
| 502 / 503 | upstream_error | Provider or gateway temporary failure. | Retry; Relixr may failover if routing allows. |
| 504 | upstream_timeout | Upstream took too long. | Retry with smaller output or another model. |
Tip
Retry 429 and most 5xx with backoff. Do not retry 402 or 403 without changing balance or the request. Use the Integration doctor to catch base URL / key mistakes before they hit production.
Future gateway builds may include docs_url and dashboard_fix on error bodies for deep links.
Next steps
Was this helpful?
Still stuck? Help center · Doctor