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

Guardrails

What can trigger a policy_violation.

Billing & credits

How balance reservation works.

Was this helpful?

Still stuck? Help center · Doctor

← Authentication OpenAPI →