Skip to main content

​
Error handling

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

​
Catching authentication failures

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

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

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

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.