Exceptions

Modus SDK exception hierarchy. All exceptions raised by the SDK are subclasses of ModusError. HTTP errors are mapped from status codes; run errors are raised from SSE events.

HTTP mapping: 401 -> AuthenticationError 403 -> PermissionDeniedError 404 -> NotFoundError 409 -> ConflictError 422 -> UnprocessableError 429 -> RateLimitError 5xx -> InternalServerError
SSE event mapping: { type: “error” } -> ModusError (raised from run/stream) { type: “cancelled” } -> RunCancelledError { type: “stream_timeout” } -> StreamTimeoutError

ModusError

exception ModusError(message: str, *, status_code: int | None = None, request_id: str | None = None, response_headers: Mapping[str, str] | None = None, body: str | None = None, code: str | None = None)

Bases: Exception Base class for all Modus SDK errors.

APIConnectionError

exception APIConnectionError(message: str)

Bases: ModusError Network-level failure (ConnectError, ReadTimeout, etc.) after all automatic retries are exhausted.

AuthenticationError

exception AuthenticationError(message: str, **kwargs: Any)

Bases: ModusError The API key is missing, invalid, or expired (HTTP 401). Check that MODUS_API_KEY is set correctly, or pass api_key= explicitly. Create a token at app.getmodus.com → Settings → API Tokens.

PermissionDeniedError

exception PermissionDeniedError(message: str, **kwargs: Any)

Bases: ModusError Raised when the API key does not have permission for the requested operation (HTTP 403).

NotFoundError

exception NotFoundError(message: str, **kwargs: Any)

Bases: ModusError The requested resource does not exist (HTTP 404).

ConflictError

exception ConflictError(message: str, **kwargs: Any)

Bases: ModusError Idempotency conflict — a run with this ID already exists with a different body (HTTP 409). Use a new idempotency key or omit it to auto-generate.

UnprocessableError

exception UnprocessableError(message: str, *, errors: Any | None = None, **kwargs: Any)

Bases: ModusError Request validation failed (HTTP 422). The errors attribute contains the full validation error detail.

RateLimitError

exception RateLimitError(message: str, *, retry_after: int | None = None, **kwargs: Any)

Bases: ModusError Rate limit exceeded (HTTP 429). The retry_after attribute contains the number of seconds to wait before retrying, if the server provided a Retry-After header. The SDK retries automatically — this error only surfaces after all retry attempts are exhausted.

InternalServerError

exception InternalServerError(message: str, *, status_code: int, **kwargs: Any)

Bases: ModusError The server encountered an internal error (HTTP 5xx). The SDK retries automatically — this error only surfaces after all retry attempts are exhausted.

RunCancelledError

exception RunCancelledError(message: str = 'Run was cancelled.')

Bases: ModusError Raised when a chat stream is cancelled before completing.

StreamTimeoutError

exception StreamTimeoutError(message: str = 'Stream timed out.')

Bases: ModusError Raised when a chat stream times out before completion.

Types

Errors

Getting Started

API Reference

ModusError

APIConnectionError

AuthenticationError

PermissionDeniedError

NotFoundError

ConflictError

UnprocessableError

RateLimitError

InternalServerError

RunCancelledError

StreamTimeoutError

​ModusError

​APIConnectionError

​AuthenticationError

​PermissionDeniedError

​NotFoundError

​ConflictError

​UnprocessableError

​RateLimitError

​InternalServerError

​RunCancelledError

​StreamTimeoutError

ModusError

APIConnectionError

AuthenticationError

PermissionDeniedError

NotFoundError

ConflictError

UnprocessableError

RateLimitError

InternalServerError

RunCancelledError

StreamTimeoutError