"""Exception hierarchy for the A2X Registry client SDK.
All errors raised by the SDK inherit from ``A2XError``. HTTP-origin errors
further inherit from ``A2XHTTPError`` and carry ``status_code`` / ``payload``;
local-only errors (e.g. ownership violations) do not.
"""
from __future__ import annotations
from typing import Any
class A2XError(Exception):
"""Base class for all SDK errors."""
def __init__(
self,
message: str,
*,
status_code: int | None = None,
payload: dict[str, Any] | None = None,
) -> None:
super().__init__(message)
self.status_code = status_code
self.payload = payload
class A2XConnectionError(A2XError):
"""Network / timeout failures (httpx.ConnectError, TimeoutException, ...)."""
class A2XHTTPError(A2XError):
"""Any 4xx/5xx response from the backend."""
class NotFoundError(A2XHTTPError):
"""404 — resource not found."""
class ValidationError(A2XHTTPError):
"""400 / 422 — request rejected by the backend."""
class A2XAuthenticationError(A2XHTTPError):
"""401 — missing, invalid, or revoked API key.
The server returned ``401 Unauthorized``. The accompanying message
usually distinguishes between "no token sent", "wrong prefix",
"hash miss", "revoked", and "principal disabled". Recovering means
fixing or replacing the credential; the same call won't succeed by
retrying.
"""
class A2XAuthorizationError(A2XHTTPError):
"""403 — authenticated but the principal lacks the required permission.
Reasons include: role too low (e.g. ``user`` trying to mutate),
namespace not in the principal's ``namespaces`` list, owner mismatch
on a per-entry mutation, or holder mismatch on lease release.
Different from 401: the token itself is valid; the operation just
isn't allowed.
"""
class UserConfigServiceImmutableError(ValidationError):
"""Update or delete refused because the service originates from ``user_config``.
The backend rejects both ``PUT`` and ``DELETE`` on services whose ``source``
is ``user_config`` — callers must edit ``user_config.json`` directly.
"""
class A2XHeartbeatNotSupportedError(ValidationError):
"""Client passed ``lease_ttl`` but the target namespace doesn't enable heartbeat.
The server's 4-corner matrix's "namespace ❌ / client ✅" cell. Inherits
from ``ValidationError`` so legacy ``except ValidationError`` paths
still catch it; new code can ``except A2XHeartbeatNotSupportedError``
for precise handling.
"""
class A2XTTLRequiredError(ValidationError):
"""Namespace requires a heartbeat lease but the client didn't supply ``lease_ttl``.
Carries the namespace's ``min_ttl`` / ``max_ttl`` bounds (parsed from
the 400 response body) so the SDK can auto-retry with a sensible
default without a second round-trip.
"""
def __init__(self, message: str, *, status_code=None, payload=None) -> None:
super().__init__(message, status_code=status_code, payload=payload)
body = payload or {}
self.min_ttl: int | None = body.get("min_ttl")
self.max_ttl: int | None = body.get("max_ttl")
class A2XTTLOutOfRangeError(ValidationError):
"""Client's ``lease_ttl`` doesn't satisfy the namespace's ``[min_ttl, max_ttl]``.
Carries the bounds for SDK / user to react. Common SDK strategy:
auto-retry once with ``min(max(client_ttl, min_ttl), max_ttl)`` if
``auto_clamp=True`` is set on the client; otherwise surface to caller.
"""
def __init__(self, message: str, *, status_code=None, payload=None) -> None:
super().__init__(message, status_code=status_code, payload=payload)
body = payload or {}
self.min_ttl: int | None = body.get("min_ttl")
self.max_ttl: int | None = body.get("max_ttl")
UserConfigDeregisterForbiddenError = UserConfigServiceImmutableError
class UnexpectedServiceTypeError(A2XHTTPError):
"""``get_agent`` received a non-JSON payload (e.g. a skill ZIP)."""
class ServerError(A2XHTTPError):
"""5xx — backend internal error."""
class NotOwnedError(A2XError):
"""Local ownership check failed; no HTTP request was sent."""
def __init__(self, dataset: str, service_id: str) -> None:
super().__init__(
f"service {service_id!r} in dataset {dataset!r} was not registered by this client"
)
self.dataset = dataset
self.service_id = service_id