Exceptions API Reference¶

Exception hierarchy for handling Honeycomb API errors.

Exception Hierarchy¶

All exceptions inherit from HoneycombAPIError, allowing you to catch all API errors with a single except clause.

HoneycombAPIError (base)
├── HoneycombAuthError (401)
├── HoneycombForbiddenError (403)
├── HoneycombNotFoundError (404)
├── HoneycombValidationError (422)
├── HoneycombRateLimitError (429)
├── HoneycombServerError (5xx)
├── HoneycombTimeoutError
└── HoneycombConnectionError

Base Exception¶

HoneycombAPIError ¶

Bases: Exception

Base exception for all Honeycomb API errors.

Attributes:

Name	Type	Description
`message`		Human-readable error message.
`status_code`		HTTP status code from the response.
`request_id`		Honeycomb request ID for support debugging (if available).
`response_body`		Raw response body (if available).

HTTP Status Exceptions¶

HoneycombAuthError ¶

Bases: HoneycombAPIError

401 Unauthorized - Invalid or missing API key.

Raised when the API key is missing, invalid, or expired.

HoneycombForbiddenError ¶

Bases: HoneycombAPIError

403 Forbidden - Insufficient permissions.

Raised when the API key doesn't have permission for the requested operation.

HoneycombNotFoundError ¶

Bases: HoneycombAPIError

404 Not Found - Resource doesn't exist.

Raised when the requested resource (dataset, trigger, SLO, etc.) is not found.

HoneycombValidationError ¶

Bases: HoneycombAPIError

422 Validation Error - Invalid request data.

Raised when the request body fails validation.

Attributes:

Name	Type	Description
`errors`		List of field-level validation errors (if available). Can be dicts, strings, or other types depending on API response format.

HoneycombRateLimitError ¶

Bases: HoneycombAPIError

429 Rate Limited - Too many requests.

Raised when the API rate limit has been exceeded.

Attributes:

Name	Type	Description
`retry_after`		Seconds to wait before retrying (if provided by API).

HoneycombServerError ¶

Bases: HoneycombAPIError

5xx Server Error - Honeycomb service issue.

Raised when Honeycomb's servers encounter an error. These errors are typically transient and can be retried.

Transport Exceptions¶

HoneycombTimeoutError ¶

Bases: HoneycombAPIError

Request timed out.

Raised when a request to the Honeycomb API times out.

HoneycombConnectionError ¶

Bases: HoneycombAPIError

Connection error.

Raised when unable to connect to the Honeycomb API.

Helper Functions¶

raise_for_status ¶

raise_for_status(
    status_code: int,
    response_body: dict | None = None,
    request_id: str | None = None,
) -> None

Raise an appropriate exception based on HTTP status code.

Parameters:

Name	Type	Description	Default
`status_code`	`int`	HTTP status code from the response.	required
`response_body`	`dict \| None`	Parsed response body (if available).	`None`
`request_id`	`str \| None`	Request ID from response headers (if available).	`None`

Raises:

Type	Description
`HoneycombAuthError`	For 401 responses.
`HoneycombForbiddenError`	For 403 responses.
`HoneycombNotFoundError`	For 404 responses.
`HoneycombValidationError`	For 422 responses.
`HoneycombRateLimitError`	For 429 responses.
`HoneycombServerError`	For 5xx responses.
`HoneycombAPIError`	For other error responses.

Usage Examples¶

Specific Exception Handling¶

from honeycomb import (
    HoneycombClient,
    HoneycombNotFoundError,
    HoneycombRateLimitError,
    HoneycombValidationError,
)

async with HoneycombClient(api_key="...") as client:
    try:
        trigger = await client.triggers.get_async("dataset", "trigger-id")
    except HoneycombNotFoundError as e:
        print(f"Trigger not found: {e.message}")
        print(f"Status: {e.status_code}")
        print(f"Request ID: {e.request_id}")
    except HoneycombRateLimitError as e:
        print(f"Rate limited! Retry after {e.retry_after} seconds")
    except HoneycombValidationError as e:
        print(f"Validation failed: {e.message}")
        for error in e.errors:
            print(f"  - {error}")

Catch-All Error Handling¶

from honeycomb import HoneycombClient, HoneycombAPIError

async with HoneycombClient(api_key="...") as client:
    try:
        result = await client.datasets.get_async("my-dataset")
    except HoneycombAPIError as e:
        print(f"API Error [{e.status_code}]: {e.message}")
        if e.request_id:
            print(f"Request ID for support: {e.request_id}")

See the Error Handling guide for more examples and best practices.