Raziel gateway error codes: 401, 402, 502, 503 explained

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.

Error response format

All gateway errors follow this structure:

{
  "type": "error",
  "error": {
    "type": "auth_error",
    "message": "Invalid or revoked Raziel key"
  }
}

string

Top-level envelope field. Always "error" for error responses.

string

Machine-readable error category. Use this field to branch your error-handling logic.

string

Human-readable description of what went wrong.

Error reference

401 — auth_error

{
  "type": "error",
  "error": {
    "type": "auth_error",
    "message": "Invalid or revoked Raziel key"
  }
}

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)

{
  "type": "error",
  "error": {
    "type": "auth_error",
    "message": "Insufficient balance — deposit more USDC"
  }
}

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

{
  "type": "error",
  "error": {
    "type": "no_listing",
    "message": "No live providers for this model — try again shortly"
  }
}

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

{
  "type": "error",
  "error": {
    "type": "upstream_error",
    "message": "All candidate providers failed — retry with backoff"
  }
}

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:

python

import time
import anthropic

client = anthropic.Anthropic(
    base_url="https://raziel.fun/gateway",
    api_key="rz_live_xxxxxxxxxxxx",
)

for attempt in range(4):
    try:
        message = client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=512,
            messages=[{"role": "user", "content": "Hello"}],
        )
        break
    except anthropic.APIStatusError as e:
        if e.status_code == 502 and attempt < 3:
            time.sleep(2 ** attempt)
        else:
            raise

If 502 errors persist across multiple retries, check the Raziel status page.

Summary table

Status	`error.type`	Cause	Action
`401`	`auth_error`	Invalid or revoked API key	Issue a new key from Customer → API Keys
`402`	`auth_error`	Insufficient USDC balance	Deposit USDC at Customer → Deposit
`503`	`no_listing`	No live providers for the requested model	Wait and retry, or switch to a different model
`502`	`upstream_error`	All candidate providers failed	Retry with exponential backoff

Get Started

Router

Teams

Billing

Reference

Raziel gateway error codes: 401, 402, 502, 503 explained

Error response format

Error reference

401 — auth_error

402 — auth_error (insufficient balance)

503 — no_listing

502 — upstream_error

Summary table