When a request to the Raziel gateway fails, the response body is a JSON object with a consistent shape. Each error has an HTTP status code, an error type string, and a human-readable message. This page lists every error you can encounter and what to do about each one.
All gateway errors follow this structure:
Top-level envelope field. Always "error" for error responses.
Machine-readable error category. Use this field to branch your error-handling logic.
Human-readable description of what went wrong.
Error reference
401 — auth_error
Your rz_live_… key is missing, malformed, or has been revoked.
What to do: Verify the key in your request matches the one issued in the dashboard. If you rotated or deleted the key, issue a new one from Customer → API Keys. Keys are shown in full only at creation — if you no longer have it, create a replacement.
402 — auth_error (insufficient balance)
Your account balance is too low to forward requests. A minimum balance of $0.05 USDC is required.
What to do: Top up your balance at Customer → Deposit. Send USDC on Solana to your vault address. Credits appear within approximately 60 seconds.
503 — no_listing
No providers are currently active and accepting requests for the model you specified.
What to do: Wait a short time and retry. Provider availability fluctuates. If the error persists for a specific model, try a different model — for example, switch from claude-opus-4-7 to claude-sonnet-4-6. See available models for the full list.
502 — upstream_error
The gateway reached one or more providers but all attempts failed before a successful response was returned.
What to do: Implement exponential backoff and retry the request. A simple starting point:
If 502 errors persist across multiple retries, check the Raziel status page.
Summary table
