> ## Documentation Index
> Fetch the complete documentation index at: https://docs.raziel.fun/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Every HTTP error status the Raziel gateway returns, what triggers each one, the response body format, and the correct remediation step for each case.

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:

```json theme={null}
{
  "type": "error",
  "error": {
    "type": "auth_error",
    "message": "Invalid or revoked Raziel key"
  }
}
```

<ResponseField name="type" type="string">
  Top-level envelope field. Always `"error"` for error responses.
</ResponseField>

<ResponseField name="error.type" type="string">
  Machine-readable error category. Use this field to branch your error-handling logic.
</ResponseField>

<ResponseField name="error.message" type="string">
  Human-readable description of what went wrong.
</ResponseField>

***

## Error reference

### 401 — auth\_error

```json theme={null}
{
  "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)

```json theme={null}
{
  "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

```json theme={null}
{
  "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](/reference/gateway-api#available-models) for the full list.

***

### 502 — upstream\_error

```json theme={null}
{
  "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 python theme={null}
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                 |