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

# Error handling

> Catch and respond to Simulacrum exceptions in production systems.

# Error handling

The SDK exposes a small hierarchy of exceptions in `simulacrum.exceptions`. Handling them intentionally keeps your pipelines resilient.

## Catching authentication failures

```python theme={null}
from simulacrum import Simulacrum
from simulacrum.exceptions import AuthError

client = Simulacrum(api_key="sim-key_id-secret")
try:
    client.forecast(series=[101, 103, 106], horizon=4, model="tempo")
except AuthError:
    rotate_api_key()
```

`AuthError` also covers the more specific `ApiKeyInvalidError`, `ApiKeyInactiveError`, and `ApiKeyExpiredError`. Use targeted handlers when you need bespoke remediation.

## Handling invalid payloads

```python theme={null}
from simulacrum.exceptions import InvalidRequestError

try:
    client.forecast(series=[[1, 2], [3, 4]], horizon=2, model="tempo")
except InvalidRequestError as exc:
    log_warning("Payload rejected", error=exc)
    raise ValueError("Forecast series must be one-dimensional")
```

The SDK catches most client-side validation errors before the request is sent. When they leak through, the API raises `InvalidRequestError` and includes context in the message.

## Dealing with quotas and concurrency

```python theme={null}
from time import sleep
from simulacrum.exceptions import QuotaExceededError, ForecastAlreadyRunningError

for attempt in range(3):
    try:
        return client.forecast(series=series, horizon=8, model="tempo")
    except QuotaExceededError:
        sleep(2 ** attempt)
    except ForecastAlreadyRunningError:
        wait_for_current_job()
raise RuntimeError("Forecast did not complete")
```

Quota errors include per-minute and per-day throttles. If retries keep failing, contact support to adjust limits.

## Logging unexpected API errors

```python theme={null}
from simulacrum.exceptions import ApiError

try:
    client.forecast(series=series, horizon=5, model="tempo")
except ApiError as exc:
    log_error("Simulacrum API error", error=exc)
    raise
```

Forward the original exception to your logging or observability stack so you can debug response payloads later.