Skip to main content
The Wrenn SDK maps every HTTP error response to a typed Python exception. Instead of inspecting raw status codes, you catch the specific exception class that matches the failure — or catch the base WrennError to handle all API errors in one place.

​
Base class

All SDK exceptions inherit from WrennError. Every instance exposes three attributes:
AttributeTypeDescription
.codestrMachine-readable error code from the API (e.g. "not_found")
.messagestrHuman-readable description of what went wrong
.status_codeintHTTP status code of the response

​
Error reference

ExceptionHTTP StatusError CodeWhen it occurs
WrennValidationError400invalid_requestBad or missing request parameters
WrennAuthenticationError401unauthorizedInvalid or missing API key
WrennForbiddenError403forbiddenAuthenticated but not authorized for this resource
WrennNotFoundError404not_foundThe requested resource does not exist
WrennConflictError409invalid_state, conflictResource is in a state that prevents the operation
WrennHostHasCapsulesError409host_has_capsulesHost still has running capsules and cannot be removed
WrennHostUnavailableError503host_unavailableNo suitable host is available to fulfill the request
WrennAgentError502agent_errorThe host agent returned an error
WrennInternalError500internal_errorUnexpected server-side error

​
WrennHostHasCapsulesError

WrennHostHasCapsulesError is a subclass of WrennConflictError and adds one extra attribute:
AttributeTypeDescription
.capsule_idslist[str]IDs of the capsules still running on the host
Use .capsule_ids to destroy or pause the blocking capsules before retrying.

​
Catching errors

​
Catch all API errors

Use WrennError as a catch-all when you want to handle any API failure uniformly: 
from wrenn import WrennError

try:
    result = capsule.commands.run("python script.py")
except WrennError as e:
    print(f"API error {e.status_code} [{e.code}]: {e.message}")

​
Catch specific errors

Import and catch the typed exception you expect: 
from wrenn import Capsule, WrennNotFoundError

try:
    capsule = Capsule.connect("cl-abc123")
except WrennNotFoundError:
    print("That capsule no longer exists.")

​
Handle multiple error types

You can match multiple exception types in a single try block: 
from wrenn import (
    WrennError,
    WrennAuthenticationError,
    WrennNotFoundError,
    WrennHostHasCapsulesError,
    WrennValidationError,
)

try:
    capsule.commands.run("./deploy.sh")
except WrennAuthenticationError:
    print("Check your WRENN_API_KEY — the request was not authenticated.")
except WrennNotFoundError:
    print("Capsule not found. It may have been destroyed.")
except WrennHostHasCapsulesError as e:
    print(f"Host is still running capsules: {e.capsule_ids}")
except WrennValidationError as e:
    print(f"Bad request: {e.message}")
except WrennError as e:
    # Fallback for any other API error
    print(f"Unexpected error [{e.code}]: {e.message}")
Always place more specific exception types before the base WrennError catch. Python evaluates except clauses in order, so a broad catch placed first will swallow the typed ones below it.

​
Importing exceptions

All exception classes are importable directly from the wrenn package: 
from wrenn import (
    WrennError,
    WrennValidationError,
    WrennAuthenticationError,
    WrennForbiddenError,
    WrennNotFoundError,
    WrennConflictError,
    WrennHostHasCapsulesError,
    WrennHostUnavailableError,
    WrennAgentError,
    WrennInternalError,
)