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

# Error handling

> ARIS SDK exceptions, API status codes, and retry recommendations.

## Exception hierarchy

All SDK errors inherit from `ArisError`.

```python theme={null}
class ArisError(Exception):
    """Base exception for ARIS SDK errors."""
```

## Common exceptions

| Exception                 | Meaning                                         | Retry |
| ------------------------- | ----------------------------------------------- | ----- |
| `ArisAuthenticationError` | Invalid or missing API key.                     | No    |
| `ArisPaymentError`        | Insufficient credits or billing rejection.      | No    |
| `ArisNodeError`           | Node timeout, disconnect, or execution failure. | Yes   |
| `ArisRateLimitError`      | Request rate exceeded.                          | Yes   |

## HTTP status mapping

| Status | Meaning                     | Action                         |
| ------ | --------------------------- | ------------------------------ |
| `400`  | Invalid request payload.    | Fix request fields and retry.  |
| `401`  | Authentication failed.      | Rotate or correct API key.     |
| `402`  | Credits required.           | Increase balance and retry.    |
| `429`  | Rate limit exceeded.        | Backoff and retry with jitter. |
| `503`  | No healthy nodes available. | Retry after short delay.       |

## Recommended pattern

```python theme={null}
from aris.client import Aris
from aris.errors import (
    ArisAuthenticationError,
    ArisPaymentError,
    ArisNodeError,
    ArisRateLimitError,
)

client = Aris(api_key="sk-aris-your-key")

try:
    response = client.generate(prompt="Generate a status summary")
except (ArisNodeError, ArisRateLimitError) as err:
    print(f"Temporary issue: {err}")
except ArisPaymentError:
    print("Insufficient credits.")
except ArisAuthenticationError:
    print("Invalid API key.")
```

<Accordion title="When not to retry">
  Do not retry malformed prompts (`400`) or invalid credentials (`401`) without changing the request.
</Accordion>