cb_events.exceptions¶

Exceptions for the Chaturbate Events client.

This module defines the exception hierarchy for API errors:

EventsError: Base exception for all API failures. AuthError: Authentication failures (HTTP 401/403). HttpStatusError: Generic HTTP status failures. ClientRequestError: HTTP 4xx failures (except auth/rate limit). RateLimitError: HTTP 429 failures. ServerError: HTTP 5xx and Cloudflare 52x failures.

Example

Handling API errors:

from cb_events import EventClient, AuthError, EventsError

try:
    async with EventClient(
        "https://eventsapi.chaturbate.com/events/user/token/"
    ) as client:
        async for event in client:
            pass
except AuthError as e:
    print(f"Authentication failed: {e}")
except EventsError as e:
    print(f"API error (HTTP {e.status_code}): {e}")

Attributes¶

`AUTH_ERROR_STATUS_CODES`	HTTP status codes indicating authentication failures.
`CF_SERVER_ERROR_CODES`	Cloudflare status codes treated as server-side failures.
`TRUNCATE_LENGTH`	Maximum characters stored in response_text to limit PII exposure in logs.

Exceptions¶

`AuthError`	Authentication failure from the Events API.
`ClientRequestError`	HTTP 4xx request failure (excluding auth and rate limiting).
`EventsError`	Base exception for API failures with optional HTTP metadata.
`HttpStatusError`	Base error for non-authentication HTTP status code failures.
`RateLimitError`	HTTP 429 rate-limiting failure.
`ServerError`	HTTP 5xx server-side failure.

Functions¶

`build_http_error`(→ EventsError)	Build the most specific HTTP status error for a status code.
`truncate_text`(→ str)	Truncate text with ellipsis if it exceeds the limit.

Module Contents¶

exception cb_events.exceptions.AuthError(message: str, *, status_code: int | None = None, response_text: str | None = None)[source]¶

Bases: EventsError

Authentication failure from the Events API.

Raised when the API returns HTTP 401 (Unauthorized) or 403 (Forbidden), typically indicating invalid credentials or an expired token.

Also raised during client initialization if username or token is empty or contains invalid whitespace.

Example

Handling authentication errors:

try:
    async with EventClient(
        "https://eventsapi.chaturbate.com/events/user/invalid_token/"
    ) as client:
        await client.poll()
except AuthError:
    print("Invalid credentials - regenerate token")

Initialize error with message and optional HTTP details.

Parameters:

message – Human-readable description of the failure.
status_code – Optional HTTP status code returned by the API.
response_text – Optional raw response body. Truncated to 200 characters to reduce PII exposure in structured exception loggers and error-reporting tools.

exception cb_events.exceptions.ClientRequestError(message: str, *, status_code: int | None = None, response_text: str | None = None)[source]¶

Bases: HttpStatusError

HTTP 4xx request failure (excluding auth and rate limiting).

Initialize error with message and optional HTTP details.

Parameters:

message – Human-readable description of the failure.
status_code – Optional HTTP status code returned by the API.
response_text – Optional raw response body. Truncated to 200 characters to reduce PII exposure in structured exception loggers and error-reporting tools.

exception cb_events.exceptions.EventsError(message: str, *, status_code: int | None = None, response_text: str | None = None)[source]¶

Bases: Exception

Base exception for API failures with optional HTTP metadata.

Raised for network errors, invalid responses, rate limiting, and other non-authentication failures. Includes HTTP status code and response body when available.

Example

Inspecting error details:

try:
    events = await client.poll()
except EventsError as e:
    if e.status_code == 429:
        print("Rate limited, backing off...")
    print(f"Response: {e.response_text}")

Initialize error with message and optional HTTP details.

Parameters:

message – Human-readable description of the failure.
status_code – Optional HTTP status code returned by the API.
response_text – Optional raw response body. Truncated to 200 characters to reduce PII exposure in structured exception loggers and error-reporting tools.

response_text: str | None[source]¶: Raw response body, truncated to 200 characters to limit PII in logs.

status_code: int | None[source]¶: HTTP status code if available.

exception cb_events.exceptions.HttpStatusError(message: str, *, status_code: int | None = None, response_text: str | None = None)[source]¶

Bases: EventsError

Base error for non-authentication HTTP status code failures.

Initialize error with message and optional HTTP details.

Parameters:

message – Human-readable description of the failure.
status_code – Optional HTTP status code returned by the API.
response_text – Optional raw response body. Truncated to 200 characters to reduce PII exposure in structured exception loggers and error-reporting tools.

exception cb_events.exceptions.RateLimitError(message: str, *, status_code: int | None = None, response_text: str | None = None)[source]¶

Bases: HttpStatusError

HTTP 429 rate-limiting failure.

Only raised after all retry attempts are exhausted; the client retries 429 responses automatically per ClientConfig.retry_attempts.

Initialize error with message and optional HTTP details.

Parameters:

message – Human-readable description of the failure.
status_code – Optional HTTP status code returned by the API.
response_text – Optional raw response body. Truncated to 200 characters to reduce PII exposure in structured exception loggers and error-reporting tools.

exception cb_events.exceptions.ServerError(message: str, *, status_code: int | None = None, response_text: str | None = None)[source]¶

Bases: HttpStatusError

HTTP 5xx server-side failure.

Initialize error with message and optional HTTP details.

Parameters:

message – Human-readable description of the failure.
status_code – Optional HTTP status code returned by the API.
response_text – Optional raw response body. Truncated to 200 characters to reduce PII exposure in structured exception loggers and error-reporting tools.

cb_events.exceptions.build_http_error(message: str, *, status_code: int, response_text: str | None = None) → EventsError[source]¶

Build the most specific HTTP status error for a status code.

Parameters:

message – Human-readable failure message.
status_code – HTTP status code returned by the API.
response_text – Optional response body.

Returns:

An instance of the most specific EventsError subclass matching the status code, with message and HTTP details included.

cb_events.exceptions.truncate_text(text: str, *, limit: int = TRUNCATE_LENGTH) → str[source]¶

Truncate text with ellipsis if it exceeds the limit.

Parameters:

text – Text to truncate.
limit – Maximum number of characters to retain.

Returns:

Text truncated to limit characters with ellipsis if needed.

Raises:

ValueError – If limit is negative.

cb_events.exceptions.AUTH_ERROR_STATUS_CODES: Final[frozenset[int]][source]¶: HTTP status codes indicating authentication failures.

cb_events.exceptions.CF_SERVER_ERROR_CODES: Final[frozenset[int]][source]¶: Cloudflare status codes treated as server-side failures.

cb_events.exceptions.TRUNCATE_LENGTH: Final[int] = 200[source]¶: Maximum characters stored in response_text to limit PII exposure in logs.