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"
}
}

Status Codes

Status	Code	Meaning
402	`insufficient_balance`	Your workspace balance can't cover the reserved cost of this request.
403	`policy_violation`	A guardrail blocked the request — see `blocked_by` for which one.
429	`rate_limited`	You've hit a rate limit on this key or workspace.

Tip:

Retry 429 with backoff — it's transient. Don't retry 402 or 403 without changing something first (top up your balance, or adjust the request that tripped a guardrail); retrying blindly just burns your rate limit budget for no gain.

Next steps

Guardrails

What can trigger a policy_violation.

Billing & credits

How balance reservation works.

← Authentication Model routing →