Skip to content

errors

Class info

Classes

Name Children Inherits
T3AuthError
pyt3client.errors
Signing in failed, or the server no longer accepts the credential.
    T3Error
    pyt3client.errors
    Base class for every error pyt3client raises.
    T3HttpError
    pyt3client.errors
    The server answered with an unexpected HTTP status.
      T3McpError
      pyt3client.errors
      The server answered a request with a JSON-RPC error.
        T3ProtocolError
        pyt3client.errors
        The server answered in a shape this client does not understand.
          T3RpcError
          pyt3client.errors
          A native RPC failed: the server ended the request with a failure, or the socket closed.
            T3ToolError
            pyt3client.errors
            A tool call was refused.

              🛈 DocStrings

              Exceptions raised by pyt3client.

              OrchestratorFailureCode

              OrchestratorFailureCode = Literal[
                  "capability_denied",
                  "parent_not_active",
                  "provider_unavailable",
                  "model_unavailable",
                  "runtime_mode_escalation_denied",
                  "interaction_mode_escalation_denied",
                  "task_not_found",
                  "task_not_cancellable",
                  "thread_not_found",
                  "run_not_found",
                  "thread_not_sendable",
                  "thread_not_interruptible",
                  "invalid_request",
                  "orchestration_error",
                  "thread_credential_required",
                  "target_required",
              ]
              

              Codes of a typed tool refusal.

              Mirrors OrchestratorMcpFailure.code in upstream packages/contracts/src/orchestratorMcp.ts. Newer servers may send codes not listed here, so T3ToolError.code is typed OrchestratorFailureCode | str.

              T3AuthError

              Bases: T3Error

              Signing in failed, or the server no longer accepts the credential.

              Raised for a rejected pairing code, a revoked or expired token (HTTP 401 on /mcp), and OAuth errors from /oauth/mcp/*.

              Source code in src/pyt3client/errors.py
              47
              48
              49
              50
              51
              52
              class T3AuthError(T3Error):
                  """Signing in failed, or the server no longer accepts the credential.
              
                  Raised for a rejected pairing code, a revoked or expired token (HTTP 401
                  on `/mcp`), and OAuth errors from `/oauth/mcp/*`.
                  """
              

              T3Error

              Bases: Exception

              Base class for every error pyt3client raises.

              Source code in src/pyt3client/errors.py
              34
              35
              class T3Error(Exception):
                  """Base class for every error pyt3client raises."""
              

              T3HttpError

              Bases: T3Error

              The server answered with an unexpected HTTP status.

              Source code in src/pyt3client/errors.py
              38
              39
              40
              41
              42
              43
              44
              class T3HttpError(T3Error):
                  """The server answered with an unexpected HTTP status."""
              
                  def __init__(self, message: str, *, status: int, body: str) -> None:
                      super().__init__(f"{message} (HTTP {status}): {body[:500]}")
                      self.status = status
                      self.body = body
              

              T3McpError

              Bases: T3Error

              The server answered a request with a JSON-RPC error.

              Unlike T3ToolError (a tool that ran and refused), this means the request itself was rejected: an unknown tool, arguments that fail the tool's input schema, or a malformed request.

              Source code in src/pyt3client/errors.py
              63
              64
              65
              66
              67
              68
              69
              70
              71
              72
              73
              74
              75
              class T3McpError(T3Error):
                  """The server answered a request with a JSON-RPC error.
              
                  Unlike `T3ToolError` (a tool that ran and refused), this means the request
                  itself was rejected: an unknown tool, arguments that fail the tool's input
                  schema, or a malformed request.
                  """
              
                  def __init__(self, method: str, code: int, message: str) -> None:
                      super().__init__(f"{method}: JSON-RPC error {code}: {message}")
                      self.method = method
                      self.code = code
                      self.message = message
              

              T3ProtocolError

              Bases: T3Error

              The server answered in a shape this client does not understand.

              Usually a version mismatch: regenerate the models against the server (see scripts/generate_models.py) or update pyt3client.

              Source code in src/pyt3client/errors.py
              55
              56
              57
              58
              59
              60
              class T3ProtocolError(T3Error):
                  """The server answered in a shape this client does not understand.
              
                  Usually a version mismatch: regenerate the models against the server
                  (see `scripts/generate_models.py`) or update pyt3client.
                  """
              

              T3RpcError

              Bases: T3Error

              A native RPC failed: the server ended the request with a failure, or the socket closed.

              Native RPC is Effect RPC over T3 Code's WebSocket (see pyt3client.native). A request that fails ends with an Exit whose cause is a typed error (Fail, such as OrchestrationV2DispatchCommandError), a defect (Die) or an interruption.

              Source code in src/pyt3client/errors.py
               92
               93
               94
               95
               96
               97
               98
               99
              100
              101
              102
              103
              104
              105
              class T3RpcError(T3Error):
                  """A native RPC failed: the server ended the request with a failure, or the socket closed.
              
                  Native RPC is Effect RPC over T3 Code's WebSocket (see `pyt3client.native`). A
                  request that fails ends with an `Exit` whose cause is a typed error (`Fail`, such
                  as `OrchestrationV2DispatchCommandError`), a defect (`Die`) or an interruption.
                  """
              
                  def __init__(self, tag: str, message: str, *, cause: object = None) -> None:
                      super().__init__(f"{tag}: {message}")
                      self.tag = tag
                      self.message = message
                      self.cause = cause
                      """The failure as the server encoded it (JSON), if any."""
              

              cause instance-attribute

              cause = cause
              

              The failure as the server encoded it (JSON), if any.

              T3ToolError

              Bases: T3Error

              A tool call was refused.

              T3 Code reports expected refusals as an MCP result with isError: true whose text is {"_tag": "OrchestratorMcpFailure", "code": ..., "message": ...}.

              Source code in src/pyt3client/errors.py
              78
              79
              80
              81
              82
              83
              84
              85
              86
              87
              88
              89
              class T3ToolError(T3Error):
                  """A tool call was refused.
              
                  T3 Code reports expected refusals as an MCP result with `isError: true`
                  whose text is `{"_tag": "OrchestratorMcpFailure", "code": ..., "message": ...}`.
                  """
              
                  def __init__(self, tool: str, code: OrchestratorFailureCode | str, message: str) -> None:
                      super().__init__(f"{tool}: {code}: {message}")
                      self.tool = tool
                      self.code = code
                      self.message = message