Alerts Exceptions

Exception hierarchy for the alerts subsystem.

Exception Hierarchy

KstlibError
└── AlertError
    ├── AlertConfigurationError
    ├── AlertDeliveryError
    └── AlertThrottledError

Base Exception

exception kstlib.alerts.exceptions.AlertError

Bases: KstlibError

Base class for all alert-related errors.

Configuration Errors

exception kstlib.alerts.exceptions.AlertConfigurationError

Bases: AlertError

Raised when alert configuration is invalid or incomplete.

Raised when alert configuration is invalid:

• Invalid webhook URL format

• Missing required parameters

• Invalid channel configuration

Delivery Errors

exception kstlib.alerts.exceptions.AlertDeliveryError(message, *, channel, retryable=False)

Bases: AlertError

Raised when an alert cannot be delivered to a channel.

channel

The name of the channel that failed.

retryable

Whether the error is potentially recoverable with retry.

Examples

>>> err = AlertDeliveryError("Connection failed", channel="slack", retryable=True)
>>> err.channel
'slack'
>>> err.retryable
True

__init__(self, message: 'str', *, channel: 'str', retryable: 'bool' = False) → 'None' -> None

Initialize AlertDeliveryError.

Parameters:

• message (str) – Error description.

• channel (str) – Name of the channel that failed.

• retryable (bool) – Whether the delivery could succeed on retry.

Raised when alert delivery fails:

• Network errors

• HTTP errors (4xx, 5xx)

• Timeout errors

The retryable attribute indicates if the operation can be retried.

Throttle Errors

exception kstlib.alerts.exceptions.AlertThrottledError(message, *, retry_after)

Bases: AlertError

Raised when an alert is throttled due to rate limiting.

retry_after

Seconds until the next alert can be sent.

Examples

>>> err = AlertThrottledError("Rate limit exceeded", retry_after=30.0)
>>> err.retry_after
30.0

__init__(self, message: 'str', *, retry_after: 'float') → 'None' -> None

Initialize AlertThrottledError.

Parameters:

• message (str) – Error description.

• retry_after (float) – Seconds until the rate limit resets.

Raised when alert is rate-limited:

• Rate limit exceeded

• Timeout waiting for token

The retry_after attribute indicates seconds until next attempt.

Usage Examples

from kstlib.alerts.exceptions import (
    AlertError,
    AlertConfigurationError,
    AlertDeliveryError,
    AlertThrottledError,
)

try:
    await channel.send(alert)
except AlertThrottledError as e:
    log.warning(f"Throttled, retry after {e.retry_after}s")
except AlertDeliveryError as e:
    if e.retryable:
        await retry_later(alert)
    else:
        log.error(f"Permanent failure: {e}")
except AlertConfigurationError as e:
    log.error(f"Config error: {e}")
except AlertError as e:
    log.error(f"Alert error: {e}")