Error Reference

All error types thrown by the library across all languages.

LiterLlmError

All errors that can occur when using liter-llm.

Variant	Message	Description
`Authentication`	authentication failed: {message}	`status` preserves the exact HTTP status code received (401 or 403).
`RateLimited`	rate limited: {message}	Rate limited errors
`BadRequest`	bad request: {message}	`status` preserves the exact HTTP status code received (400, 405, 413, 422, …).
`ContextWindowExceeded`	context window exceeded: {message}	Context window exceeded errors
`ContentPolicy`	content policy violation: {message}	Content policy errors
`NotFound`	not found: {message}	Not found errors
`ServerError`	server error: {message}	`status` preserves the exact HTTP status code received (500, or other 5xx not covered by `ServiceUnavailable`).
`ServiceUnavailable`	service unavailable: {message}	`status` preserves the exact HTTP status code received (502, 503, or 504).
`Timeout`	request timeout	Timeout errors
`Streaming`	streaming error: {message}	A catch-all for errors that occur during streaming response processing. This variant covers multiple sub-conditions including UTF-8 decoding failures, CRC/checksum mismatches (AWS EventStream), JSON parse errors in individual SSE chunks, and buffer overflow conditions. The `message` field contains a human-readable description of the specific failure.
`EndpointNotSupported`	provider {provider} does not support {endpoint}	Endpoint not supported errors
`InvalidHeader`	invalid header {name:?}: {reason}	Invalid header errors
`Serialization`	serialization error: {0}	Serialization errors
`BudgetExceeded`	budget exceeded: {message}	Budget exceeded errors
`HookRejected`	hook rejected: {message}	Hook rejected errors
`InternalError`	internal error: {message}	An internal logic error (e.g. unexpected Tower response variant). This should never surface in normal operation — if it does, it indicates a bug in the library.
`OutboundForbidden`	outbound request to {url} forbidden: {reason}	An outbound request was blocked by the active `OutboundPolicy`. Returned when `register_custom_provider` is called with a `base_url` that violates the policy (e.g. a private-range IP under `DenyPrivate`), or when the per-connection DNS resolver detects a forbidden address at connect time.
`IdempotencyConflict`	idempotency conflict: key ‘{key}’ was already used with a different request body	A different request body was submitted for an existing `Idempotency-Key`. Per the OpenAI `Idempotency-Key` convention, once a key is used with a particular request body, subsequent requests using the same key must carry an identical body. A body mismatch is a hard error (not retryable). HTTP equivalent: 409 Conflict.
`IdempotencyInFlight`	idempotency key ‘{key}’ is currently in-flight; retry after the first request completes	The same `Idempotency-Key` is already in-flight (another request with the same key is currently being processed). The caller should wait briefly and retry. The response is not yet available, and this request has been short-circuited to avoid running the operation twice. HTTP equivalent: 409 Conflict (retryable after a brief delay).

CatalogRefreshError

Errors from refresh_catalog and install_catalog_overlay_from_str.

On every variant, the overlay registry is left untouched: a previously installed overlay (or the embedded catalog, if none was ever installed) remains active. This is the air-gap-safety contract — a failed refresh never degrades pricing/model-info availability.

Variant	Message	Description
`Disabled`	catalog refresh is disabled	Runtime catalog refresh was not enabled. `refresh_catalog` itself never returns this — it returns `Ok(RefreshOutcome.Disabled)` instead — but the variant is part of the public error surface for callers that want to treat “disabled” as a hard error.
`InsecureUrl`	insecure catalog source URL {url:?}: only https is allowed	`source_url` did not use the `https` scheme, or failed to parse as a URL at all. There is no host allowlist: the URL is user-configurable for self-hosted catalog mirrors, so only the scheme is enforced.
`Fetch`	failed to fetch catalog from {url}: {message}	The network fetch failed, timed out, or returned a non-success status.
`Parse`	failed to parse catalog JSON: {message}	The fetched or cached catalog JSON failed to parse.
`Cache`	catalog cache I/O error at {path}: {message}	A cache file read failed on an otherwise-fresh cache file. Cache write failures are best-effort and never surface as this error (see `refresh_catalog`).