> ## 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.

# Exception hierarchy

> Errors raised by the Simulacrum SDK and how to react to them.

# Exception hierarchy

Import exceptions from `simulacrum.exceptions` as needed. All SDK-specific errors subclass `SimulacrumError`.

| Exception                     | Description                                                        |
| ----------------------------- | ------------------------------------------------------------------ |
| `SimulacrumError`             | Base class; catch when you want to handle all SDK errors.          |
| `AuthError`                   | Authentication failed (covers invalid, inactive, or expired keys). |
| `ApiKeyInvalidError`          | API key is unknown to the platform.                                |
| `ApiKeyInactiveError`         | API key has been disabled administratively.                        |
| `ApiKeyExpiredError`          | API key has passed its expiration timestamp.                       |
| `QuotaExceededError`          | Request rejected because you exceeded usage limits.                |
| `ForecastAlreadyRunningError` | The same forecast job is currently in progress.                    |
| `InvalidRequestError`         | Payload failed server-side validation.                             |
| `ApiError`                    | Generic API or parsing failure.                                    |

## Usage patterns

```python theme={null}
from simulacrum.exceptions import (
    AuthError,
    ForecastAlreadyRunningError,
    QuotaExceededError,
    SimulacrumError,
)

try:
    forecast = client.forecast(series, horizon=12)
except AuthError:
    rotate_key()
except ForecastAlreadyRunningError:
    wait_for_job()
except QuotaExceededError:
    backoff()
except SimulacrumError as exc:
    log_error("Unhandled Simulacrum error", error=exc)
    raise
```

The `ERROR_CODE_MAP` constant inside the module surfaces the mapping between API `error_code` values and exception classes. Extend your handlers as new codes are introduced.