Python Error Handling

The SDK raises typed exceptions for API failures, validation issues, and network problems. The taxonomy mirrors the API’s ErrorResponse envelope, with subclasses per HTTP class for ergonomic catching.

Exception hierarchy

DevhelmError                  ← umbrella; catch as a fallback
├── DevhelmValidationError    ← local request/response shape validation
├── DevhelmTransportError     ← connection refused, DNS, TLS, timeout
└── DevhelmApiError           ← non-2xx HTTP response
    ├── DevhelmAuthError      ← 401, 403
    ├── DevhelmNotFoundError  ← 404
    ├── DevhelmConflictError  ← 409
    ├── DevhelmRateLimitError ← 429
    └── DevhelmServerError    ← 5xx

All classes are importable from devhelm:

from devhelm import (
    DevhelmError,
    DevhelmValidationError,
    DevhelmApiError,
    DevhelmAuthError,
    DevhelmNotFoundError,
    DevhelmConflictError,
    DevhelmRateLimitError,
    DevhelmServerError,
    DevhelmTransportError,
)

DevhelmApiError

The most common error class — raised for any non-2xx HTTP response.

Attribute	Type	Description
`status`	`int`	HTTP status code (e.g. `404`)
`code`	`str`	Coarse machine-readable category from `ErrorResponse.code` (e.g. `"NOT_FOUND"`). Defaults to `"API_ERROR"` if the server didn’t supply one.
`message`	`str`	Human-readable message — for logs and user-facing copy
`detail`	`str \| None`	Additional context, when available
`body`	`dict \| str \| None`	Raw parsed response body for debugging
`request_id`	`str \| None`	Per-request id from the `X-Request-Id` response header. Always include in support tickets.
`retry_after`	`int \| None`	Seconds from the `Retry-After` header, when present (429)

from devhelm import DevhelmApiError

try:
    client.monitors.get("missing")
except DevhelmApiError as e:
    print(e.status)       # 404
    print(e.code)         # "NOT_FOUND"
    print(e.request_id)   # "req_01HJV..."
    print(e.message)

DevhelmValidationError

Raised before HTTP I/O when a request body fails Pydantic validation, and after a successful response when the response body doesn’t match the expected schema (rare — usually indicates a stale SDK).

Attribute	Type	Description
`message`	`str`	What failed validation
`errors`	`list`	Pydantic-style error records with `loc`, `msg`, `type`

from devhelm import DevhelmValidationError

try:
    client.monitors.create({"type": "HTTP"})  # missing required fields
except DevhelmValidationError as e:
    for err in e.errors:
        print(f"{err['loc']}: {err['msg']}")

DevhelmTransportError

Wraps httpx network failures (connection refused, DNS, TLS handshake, timeout) so callers don’t need to import httpx. The original exception is on __cause__.

from devhelm import DevhelmTransportError

try:
    client.monitors.list()
except DevhelmTransportError as e:
    print(f"Network error: {e}")
    print(f"Underlying: {e.__cause__!r}")

Handling patterns

Catch by HTTP class

from devhelm import (
    DevhelmAuthError, DevhelmNotFoundError, DevhelmRateLimitError, DevhelmError,
)

try:
    monitor = client.monitors.get(monitor_id)
except DevhelmAuthError:
    print("Bad token or insufficient permissions")
except DevhelmNotFoundError:
    print(f"Monitor {monitor_id} no longer exists")
except DevhelmRateLimitError as e:
    print(f"Rate limited (request_id={e.request_id})")
except DevhelmError:
    raise

Retry on rate limits and 5xx

import time
from devhelm import DevhelmRateLimitError, DevhelmServerError, DevhelmTransportError

def with_retry(fn, *, max_retries=3, base_delay=1.0):
    for attempt in range(max_retries + 1):
        try:
            return fn()
        except (DevhelmRateLimitError, DevhelmServerError, DevhelmTransportError) as e:
            if attempt == max_retries:
                raise
            delay = base_delay * (2 ** attempt)
            time.sleep(delay)

monitors = with_retry(client.monitors.list)

Don’t retry on DevhelmValidationError, DevhelmAuthError, DevhelmNotFoundError, or DevhelmConflictError — these are deterministic and won’t change without code or config changes.

Deploy lock contention

from devhelm import DevhelmConflictError

try:
    lock = client.deploy_lock.acquire({
        "lockedBy": "ci-pipeline",
        "ttlMinutes": 30,
    })
except DevhelmConflictError:
    current = client.deploy_lock.current()
    if current:
        print(f"Lock held by {current.locked_by} (since {current.locked_at})")

Catch-all logging

from devhelm import DevhelmApiError, DevhelmError

try:
    do_work(client)
except DevhelmApiError as e:
    log.error(
        "DevHelm API error",
        extra={
            "status": e.status,
            "code": e.code,
            "request_id": e.request_id,
            "detail": e.detail,
        },
    )
except DevhelmError:
    log.exception("DevHelm SDK error")

Wait timeouts

client.inboxes.wait, inbox.wait, client.email.wait, and address.wait hold the request open until a match arrives. These are the errors they and the other testing calls raise:

Status	Class	Check	Meaning
408	`DevhelmApiError` (no subclass)	`e.code == "WAIT_TIMEOUT"`	Nothing matched before `timeout_ms`. Often `received_after` was taken after the item arrived
429	`DevhelmRateLimitError`	`e.retry_after` (seconds)	Over 40 waits per minute. The budget is shared by every wait in the organization, inboxes and email
403	`DevhelmAuthError`	`e.code`, for example `INBOUND_EVENTS_MONTHLY_LIMIT_REACHED`	A testing plan quota on create or inject, not a bad key

There is no timeout subclass. A 408 is a plain DevhelmApiError, so check code, and catch DevhelmRateLimitError first.
The SDK does not retry. Retrying a wait is safe: wait does not consume, so the same received_after finds the same item.
The HTTP timeout is timeout_ms plus 10 seconds, so the 408 arrives first. Set your test runner’s timeout above timeout_ms.

import time
from datetime import datetime, timezone

from devhelm import DevhelmApiError, DevhelmRateLimitError
from devhelm.resources.inboxes import Event


def wait_or_none(inbox_id: str, since: datetime, timeout_ms: int = 30_000) -> Event | None:
    """The matching event, or None if none arrived before the timeout."""
    for attempt in range(1, 4):
        try:
            return client.inboxes.wait(inbox_id, received_after=since, timeout_ms=timeout_ms)
        except DevhelmRateLimitError as e:
            if attempt == 3:
                raise
            time.sleep(e.retry_after or 5)
        except DevhelmApiError as e:
            if e.code == "WAIT_TIMEOUT":
                return None
            raise
    return None


# Negative assertion: a cancelled order must not send a webhook.
since = datetime.now(timezone.utc)
cancel_order(42)
assert wait_or_none(inbox_id, since, timeout_ms=10_000) is None

A negative assertion spends one wait from the shared budget. Give it a timeout that covers your sender’s latency plus a few seconds of storage lag. See Wait for a webhook in a test and Limits, quotas, and errors.

Overview

TypeScript SDK

Python SDK

MCP Server

AI Skills

Python Error Handling

Exception hierarchy

DevhelmApiError

DevhelmValidationError

DevhelmTransportError

Handling patterns

Catch by HTTP class

Retry on rate limits and 5xx

Deploy lock contention

Catch-all logging

Wait timeouts

Next steps

Client reference

Error patterns

​Exception hierarchy

​DevhelmApiError

​DevhelmValidationError

​DevhelmTransportError

​Handling patterns

​Catch by HTTP class

​Retry on rate limits and 5xx

​Deploy lock contention

​Catch-all logging

​Wait timeouts

​Next steps

Client reference

Error patterns

Exception hierarchy

DevhelmApiError

DevhelmValidationError

DevhelmTransportError

Handling patterns

Catch by HTTP class

Retry on rate limits and 5xx

Deploy lock contention

Catch-all logging

Wait timeouts

Next steps