Exceptions

See the errors guide for the hierarchy and how to catch them.

Base and status errors

OpencodeError

Bases: Exception

Base class for every error raised by this package.

APIError

APIError(
    message: str, request: Request, *, body: object | None
)

Bases: OpencodeError

An error that happened while talking to the OpenCode server.

message instance-attribute

message: str = message

request instance-attribute

request: Request = request

body instance-attribute

body: object | None = body

The decoded JSON error body, the raw text when it is not JSON, or None.

APIConnectionError

APIConnectionError(
    *, request: Request, message: str = "Connection error."
)

Bases: APIError

The request could not reach the server, or the connection broke before a response arrived.

APITimeoutError

APITimeoutError(request: Request)

Bases: APIConnectionError

The request timed out.

APIResponseValidationError

APIResponseValidationError(
    response: Response,
    body: object | None,
    *,
    message: str | None = None,
)

Bases: APIError

The server answered, but the response does not match the expected shape.

response instance-attribute

response: Response = response

status_code instance-attribute

status_code: int = response.status_code

APIStatusError

APIStatusError(
    message: str, *, response: Response, body: object | None
)

Bases: APIError

The server returned a non-success HTTP status.

status class-attribute

status: int | None = None

The HTTP status this class represents, or None for the generic base.

tag class-attribute

tag: str | None = None

The server _tag this class represents, or None for status-only classes.

response instance-attribute

response: Response = response

status_code instance-attribute

status_code: int = response.status_code

error_tag instance-attribute

error_tag: str | None = _string_field(body, '_tag')

The _tag the server sent, which can be a tag this client version does not know yet.

request_id property

request_id: str | None

The server's request identifier, when it sends one.

BadRequestError

BadRequestError(
    message: str, *, response: Response, body: object | None
)

Bases: APIStatusError

The server rejected the request as malformed (400).

status class-attribute instance-attribute

status = 400

AuthenticationError

AuthenticationError(
    message: str, *, response: Response, body: object | None
)

Bases: APIStatusError

The password was missing or wrong (401).

status class-attribute instance-attribute

status = 401

PermissionDeniedError

PermissionDeniedError(
    message: str, *, response: Response, body: object | None
)

Bases: APIStatusError

The request is not allowed (403).

status class-attribute instance-attribute

status = 403

NotFoundError

NotFoundError(
    message: str, *, response: Response, body: object | None
)

Bases: APIStatusError

The requested resource does not exist (404).

status class-attribute instance-attribute

status = 404

ConflictError

ConflictError(
    message: str, *, response: Response, body: object | None
)

Bases: APIStatusError

The request conflicts with the current state, for example a busy session (409).

status class-attribute instance-attribute

status = 409

tag class-attribute instance-attribute

tag = 'ConflictError'

ContentTooLargeError

ContentTooLargeError(
    message: str, *, response: Response, body: object | None
)

Bases: APIStatusError

The request body is too large (413).

status class-attribute instance-attribute

status = 413

UnprocessableEntityError

UnprocessableEntityError(
    message: str, *, response: Response, body: object | None
)

Bases: APIStatusError

The request was well formed but could not be processed (422).

status class-attribute instance-attribute

status = 422

RateLimitError

RateLimitError(
    message: str, *, response: Response, body: object | None
)

Bases: APIStatusError

Too many requests (429). Retried automatically, honoring Retry-After.

status class-attribute instance-attribute

status = 429

InternalServerError

InternalServerError(
    message: str, *, response: Response, body: object | None
)

Bases: APIStatusError

The server failed (500, and the base class for every 5xx).

status class-attribute instance-attribute

status = 500

NotImplementedServerError

NotImplementedServerError(
    message: str, *, response: Response, body: object | None
)

Bases: InternalServerError

The server does not implement this endpoint (501).

status class-attribute instance-attribute

status = 501

ServiceUnavailableError

ServiceUnavailableError(
    message: str, *, response: Response, body: object | None
)

Bases: InternalServerError

The server is temporarily unavailable (503). Retried automatically.

status class-attribute instance-attribute

status = 503

tag class-attribute instance-attribute

tag = 'ServiceUnavailableError'

Declared server errors

Raised when the server returns an error it declares in its contract. Each has a typed body on .error.

AgentNotFoundError

AgentNotFoundError(
    message: str, *, response: Response, body: object | None
)

Bases: NotFoundError

The server answered 404 with _tag AgentNotFoundError.

tag class-attribute instance-attribute

tag = 'AgentNotFoundError'

error property

error: AgentNotFoundErrorBody

The error body as a typed model.

CommandExecutionError

CommandExecutionError(
    message: str, *, response: Response, body: object | None
)

Bases: InternalServerError

The server answered 500 with _tag CommandExecutionError.

tag class-attribute instance-attribute

tag = 'CommandExecutionError'

error property

error: CommandExecutionErrorBody

The error body as a typed model.

CommandNotFoundError

CommandNotFoundError(
    message: str, *, response: Response, body: object | None
)

Bases: NotFoundError

The server answered 404 with _tag CommandNotFoundError.

tag class-attribute instance-attribute

tag = 'CommandNotFoundError'

error property

error: CommandNotFoundErrorBody

The error body as a typed model.

ForbiddenError

ForbiddenError(
    message: str, *, response: Response, body: object | None
)

Bases: PermissionDeniedError

The server answered 403 with _tag ForbiddenError.

tag class-attribute instance-attribute

tag = 'ForbiddenError'

error property

error: ForbiddenErrorBody

The error body as a typed model.

FormAlreadySettledError

FormAlreadySettledError(
    message: str, *, response: Response, body: object | None
)

Bases: ConflictError

The server answered 409 with _tag FormAlreadySettledError.

tag class-attribute instance-attribute

tag = 'FormAlreadySettledError'

error property

error: FormAlreadySettledErrorBody

The error body as a typed model.

FormInvalidAnswerError

FormInvalidAnswerError(
    message: str, *, response: Response, body: object | None
)

Bases: BadRequestError

The server answered 400 with _tag FormInvalidAnswerError.

tag class-attribute instance-attribute

tag = 'FormInvalidAnswerError'

error property

error: FormInvalidAnswerErrorBody

The error body as a typed model.

FormNotFoundError

FormNotFoundError(
    message: str, *, response: Response, body: object | None
)

Bases: NotFoundError

The server answered 404 with _tag FormNotFoundError.

tag class-attribute instance-attribute

tag = 'FormNotFoundError'

error property

error: FormNotFoundErrorBody

The error body as a typed model.

InstructionEntryValueTooLargeError

InstructionEntryValueTooLargeError(
    message: str, *, response: Response, body: object | None
)

Bases: ContentTooLargeError

The server answered 413 with _tag InstructionEntryValueTooLargeError.

tag class-attribute instance-attribute

tag = 'InstructionEntryValueTooLargeError'

error property

error: InstructionEntryValueTooLargeErrorBody

The error body as a typed model.

IntegrationAttemptNotFoundError

IntegrationAttemptNotFoundError(
    message: str, *, response: Response, body: object | None
)

Bases: NotFoundError

The server answered 404 with _tag IntegrationAttemptNotFoundError.

tag class-attribute instance-attribute

tag = 'IntegrationAttemptNotFoundError'

error property

error: IntegrationAttemptNotFoundErrorBody

The error body as a typed model.

IntegrationMethodNotFoundError

IntegrationMethodNotFoundError(
    message: str, *, response: Response, body: object | None
)

Bases: NotFoundError

The server answered 404 with _tag IntegrationMethodNotFoundError.

tag class-attribute instance-attribute

tag = 'IntegrationMethodNotFoundError'

error property

error: IntegrationMethodNotFoundErrorBody

The error body as a typed model.

IntegrationNotFoundError

IntegrationNotFoundError(
    message: str, *, response: Response, body: object | None
)

Bases: NotFoundError

The server answered 404 with _tag IntegrationNotFoundError.

tag class-attribute instance-attribute

tag = 'IntegrationNotFoundError'

error property

error: IntegrationNotFoundErrorBody

The error body as a typed model.

InvalidCursorError

InvalidCursorError(
    message: str, *, response: Response, body: object | None
)

Bases: BadRequestError

The server answered 400 with _tag InvalidCursorError.

tag class-attribute instance-attribute

tag = 'InvalidCursorError'

error property

error: InvalidCursorErrorBody

The error body as a typed model.

InvalidRequestError

InvalidRequestError(
    message: str, *, response: Response, body: object | None
)

Bases: BadRequestError

The server answered 400 with _tag InvalidRequestError.

tag class-attribute instance-attribute

tag = 'InvalidRequestError'

error property

error: InvalidRequestErrorBody

The error body as a typed model.

LocationNotFoundError

LocationNotFoundError(
    message: str, *, response: Response, body: object | None
)

Bases: NotFoundError

The server answered 404 with _tag LocationNotFoundError.

tag class-attribute instance-attribute

tag = 'LocationNotFoundError'

error property

error: LocationNotFoundErrorBody

The error body as a typed model.

McpServerNotFoundError

McpServerNotFoundError(
    message: str, *, response: Response, body: object | None
)

Bases: NotFoundError

The server answered 404 with _tag McpServerNotFoundError.

tag class-attribute instance-attribute

tag = 'McpServerNotFoundError'

error property

error: McpServerNotFoundErrorBody

The error body as a typed model.

MessageNotFoundError

MessageNotFoundError(
    message: str, *, response: Response, body: object | None
)

Bases: NotFoundError

The server answered 404 with _tag MessageNotFoundError.

tag class-attribute instance-attribute

tag = 'MessageNotFoundError'

error property

error: MessageNotFoundErrorBody

The error body as a typed model.

PermissionNotFoundError

PermissionNotFoundError(
    message: str, *, response: Response, body: object | None
)

Bases: NotFoundError

The server answered 404 with _tag PermissionNotFoundError.

tag class-attribute instance-attribute

tag = 'PermissionNotFoundError'

error property

error: PermissionNotFoundErrorBody

The error body as a typed model.

PermissionSavedNotFoundError

PermissionSavedNotFoundError(
    message: str, *, response: Response, body: object | None
)

Bases: NotFoundError

The server answered 404 with _tag PermissionSavedNotFoundError.

tag class-attribute instance-attribute

tag = 'PermissionSavedNotFoundError'

error property

error: PermissionSavedNotFoundErrorBody

The error body as a typed model.

ProjectNotFoundError

ProjectNotFoundError(
    message: str, *, response: Response, body: object | None
)

Bases: NotFoundError

The server answered 404 with _tag ProjectNotFoundError.

tag class-attribute instance-attribute

tag = 'ProjectNotFoundError'

error property

error: ProjectNotFoundErrorBody

The error body as a typed model.

ProviderNotFoundError

ProviderNotFoundError(
    message: str, *, response: Response, body: object | None
)

Bases: NotFoundError

The server answered 404 with _tag ProviderNotFoundError.

tag class-attribute instance-attribute

tag = 'ProviderNotFoundError'

error property

error: ProviderNotFoundErrorBody

The error body as a typed model.

PtyNotFoundError

PtyNotFoundError(
    message: str, *, response: Response, body: object | None
)

Bases: NotFoundError

The server answered 404 with _tag PtyNotFoundError.

tag class-attribute instance-attribute

tag = 'PtyNotFoundError'

error property

error: PtyNotFoundErrorBody

The error body as a typed model.

RemoteFileNotFoundError

RemoteFileNotFoundError(
    message: str, *, response: Response, body: object | None
)

Bases: NotFoundError

The server answered 404 with _tag FileNotFoundError.

tag class-attribute instance-attribute

tag = 'FileNotFoundError'

error property

error: FileNotFoundErrorBody

The error body as a typed model.

RpcError

RpcError(
    message: str, *, response: Response, body: object | None
)

Bases: BadRequestError

The server answered 400 with _tag RpcError.

tag class-attribute instance-attribute

tag = 'RpcError'

error property

error: RpcErrorBody

The error body as a typed model.

RpcInternalError

RpcInternalError(
    message: str, *, response: Response, body: object | None
)

Bases: InternalServerError

The server answered 500 with _tag RpcInternalError.

tag class-attribute instance-attribute

tag = 'RpcInternalError'

error property

error: RpcInternalErrorBody

The error body as a typed model.

SessionBusyError

SessionBusyError(
    message: str, *, response: Response, body: object | None
)

Bases: ConflictError

The server answered 409 with _tag SessionBusyError.

tag class-attribute instance-attribute

tag = 'SessionBusyError'

error property

error: SessionBusyErrorBody

The error body as a typed model.

SessionNotFoundError

SessionNotFoundError(
    message: str, *, response: Response, body: object | None
)

Bases: NotFoundError

The server answered 404 with _tag SessionNotFoundError.

tag class-attribute instance-attribute

tag = 'SessionNotFoundError'

error property

error: SessionNotFoundErrorBody

The error body as a typed model.

ShellNotFoundError

ShellNotFoundError(
    message: str, *, response: Response, body: object | None
)

Bases: NotFoundError

The server answered 404 with _tag ShellNotFoundError.

tag class-attribute instance-attribute

tag = 'ShellNotFoundError'

error property

error: ShellNotFoundErrorBody

The error body as a typed model.

SkillNotFoundError

SkillNotFoundError(
    message: str, *, response: Response, body: object | None
)

Bases: NotFoundError

The server answered 404 with _tag SkillNotFoundError.

tag class-attribute instance-attribute

tag = 'SkillNotFoundError'

error property

error: SkillNotFoundErrorBody

The error body as a typed model.

UnauthorizedError

UnauthorizedError(
    message: str, *, response: Response, body: object | None
)

Bases: AuthenticationError

The server answered 401 with _tag UnauthorizedError.

tag class-attribute instance-attribute

tag = 'UnauthorizedError'

error property

error: UnauthorizedErrorBody

The error body as a typed model.

UnknownError

UnknownError(
    message: str, *, response: Response, body: object | None
)

Bases: InternalServerError

The server answered 500 with _tag UnknownError.

tag class-attribute instance-attribute

tag = 'UnknownError'

error property

error: UnknownErrorBody

The error body as a typed model.

VcsInitNotSupportedError

VcsInitNotSupportedError(
    message: str, *, response: Response, body: object | None
)

Bases: NotImplementedServerError

The server answered 501 with _tag VcsInitNotSupportedError.

tag class-attribute instance-attribute

tag = 'VcsInitNotSupportedError'

error property

error: VcsInitNotSupportedErrorBody

The error body as a typed model.

WorktreeError

WorktreeError(
    message: str, *, response: Response, body: object | None
)

Bases: BadRequestError

The server answered 400 with _tag WorktreeError.

tag class-attribute instance-attribute

tag = 'WorktreeError'

error property

error: WorktreeErrorBody

The error body as a typed model.