Skip to main content

​
Exception Hierarchy

TerminalUseError
└── APIError
    ├── APIStatusError
    │   ├── BadRequestError (400)
    │   ├── AuthenticationError (401)
    │   ├── PermissionDeniedError (403)
    │   ├── NotFoundError (404)
    │   ├── ConflictError (409)
    │   ├── UnprocessableEntityError (422)
    │   ├── RateLimitError (429)
    │   └── InternalServerError (5xx)
    ├── APITimeoutError
    ├── APIConnectionError
    └── APIResponseValidationError

​
Common Errors

​
BadRequestError (400)

Invalid request parameters. 
from terminaluse import BadRequestError

try:
    client.agents.deploy(agent_name="invalid name!")
except BadRequestError as e:
    print(f"Invalid request: {e.message}")

​
AuthenticationError (401)

Invalid or expired credentials. 
from terminaluse import AuthenticationError

try:
    client.agents.list()
except AuthenticationError:
    print("Please login: tu login")

​
PermissionDeniedError (403)

Insufficient permissions. 
from terminaluse import PermissionDeniedError

try:
    client.agents.delete("agent-id")
except PermissionDeniedError:
    print("You don't have permission to delete this agent")

​
NotFoundError (404)

Resource not found. 
from terminaluse import NotFoundError

try:
    agent = client.agents.retrieve("nonexistent")
except NotFoundError:
    print("Agent not found")

​
RateLimitError (429)

Too many requests. 
from terminaluse import RateLimitError
import time

try:
    client.agents.list()
except RateLimitError as e:
    retry_after = e.response.headers.get("Retry-After", 60)
    time.sleep(int(retry_after))

​
InternalServerError (5xx)

Server-side error. 
from terminaluse import InternalServerError

try:
    client.agents.list()
except InternalServerError:
    print("Server error - try again later")

​
Error Properties

try:
    client.agents.retrieve("id")
except APIStatusError as e:
    print(e.status_code)   # HTTP status code
    print(e.message)       # Error message
    print(e.response)      # Raw httpx.Response
    print(e.body)          # Response body

​
Retry Behavior

The SDK automatically retries on:
  • 408 Request Timeout
  • 409 Conflict
  • 429 Rate Limit
  • 5xx Server Errors
# Configure retries
client = Client(max_retries=5)

# Disable retries
client = Client(max_retries=0)

​
Error Handling Pattern

from terminaluse import (
    Client,
    APIError,
    AuthenticationError,
    RateLimitError,
    NotFoundError,
)
import time

client = Client()

def get_agent(agent_id: str):
    try:
        return client.agents.retrieve(agent_id)

    except AuthenticationError:
        # Re-authenticate
        raise

    except NotFoundError:
        # Handle missing resource
        return None

    except RateLimitError:
        # Wait and retry
        time.sleep(60)
        return get_agent(agent_id)

    except APIError as e:
        # Log and re-raise
        logger.error(f"API error: {e}")
        raise