Errors

llm-rotate raises a small, predictable set of exceptions and internally classifies every provider failure into an error type that drives the rotation logic.

Exception hierarchy#

All exceptions are exported from llm_rotate.

ConfigurationError#

Raised for invalid configuration or misuse — for example using lm before configure(), calling configure() twice, or a model whose provider can't be inferred and has no fallback chain. These are programmer errors; fix them at startup.

LMRotateError#

The base runtime error for a call that failed in a way that isn't simply "all keys exhausted". Carries provider, error_type, and a masked key_id.

LMRotateError(message, *, provider=None, error_type=None, key_id=None)

NoAvailableKeyError#

Raised when every eligible key — across the native provider and any fallback chain — is unavailable. Includes:

• model — the requested model
• health_report — the current health snapshot
• earliest_retry_at — when a key is next expected to become available

This is the natural mapping to an HTTP 503.

from llm_rotate import lm, NoAvailableKeyError
 
try:
    resp = await lm.chat("gpt-4o-mini", [{"role": "user", "content": "Hi"}])
except NoAvailableKeyError as e:
    # back off until e.earliest_retry_at, surface a 503, etc.
    ...

Error taxonomy#

Internally, each provider failure is classified into an ErrorType. This is what decides whether a call rotates to another key, retries with backoff, or fails fast.