honkio 0.1.0__py3-none-any.whl

honkio/__init__.py

@@ -0,0 +1,53 @@
+"""Official Python SDK for HonkIO: Canadian SMS and email, CASL built in."""
+
+from ._client import AsyncHonkio, Honkio
+from ._core import NOT_GIVEN, NotGiven
+from ._endpoints import ENDPOINTS, Endpoint
+from ._errors import (
+    APIConnectionError,
+    ApiError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    HonkioError,
+    InternalServerError,
+    InvalidArgumentError,
+    InvalidSignatureError,
+    NotFoundError,
+    PaymentRequiredError,
+    PermissionDeniedError,
+    RateLimitError,
+    UnavailableForLegalReasonsError,
+    UnprocessableEntityError,
+)
+from ._version import __version__
+from ._webhooks import WEBHOOK_EVENTS, verify_webhook
+
+__all__ = [
+    "ENDPOINTS",
+    "NOT_GIVEN",
+    "WEBHOOK_EVENTS",
+    "APIConnectionError",
+    "APITimeoutError",
+    "ApiError",
+    "AsyncHonkio",
+    "AuthenticationError",
+    "BadRequestError",
+    "ConflictError",
+    "Endpoint",
+    "Honkio",
+    "HonkioError",
+    "InternalServerError",
+    "InvalidArgumentError",
+    "InvalidSignatureError",
+    "NotGiven",
+    "NotFoundError",
+    "PaymentRequiredError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "UnavailableForLegalReasonsError",
+    "UnprocessableEntityError",
+    "__version__",
+    "verify_webhook",
+]

honkio/_client.py

@@ -0,0 +1,139 @@
+"""The sync and async clients."""
+
+from __future__ import annotations
+
+from types import TracebackType
+
+import httpx
+
+from ._core import DEFAULT_BASE_URL, DEFAULT_TIMEOUT
+from ._transport import AsyncTransport, SyncTransport
+from .resources import (
+    AsyncAutoTopupResource,
+    AsyncBatch,
+    AsyncBusinessVerificationResource,
+    AsyncConsentBatches,
+    AsyncConsents,
+    AsyncDomains,
+    AsyncEmails,
+    AsyncMessages,
+    AsyncOptInConfirmations,
+    AsyncPhoneNumbers,
+    AsyncSuppressions,
+    AsyncTemplates,
+    AsyncTollFreeVerifications,
+    AsyncTopupCapRequests,
+    AsyncVerify,
+    AsyncWebhooks,
+    AutoTopupResource,
+    Batch,
+    BusinessVerificationResource,
+    ConsentBatches,
+    Consents,
+    Domains,
+    Emails,
+    Messages,
+    OptInConfirmations,
+    PhoneNumbers,
+    Suppressions,
+    Templates,
+    TollFreeVerifications,
+    TopupCapRequests,
+    Verify,
+    Webhooks,
+)
+
+
+class Honkio:
+    """The HonkIO client.
+
+    The key comes from `api_key` or the HONKIO_API_KEY environment variable. A client built
+    without `http_client` owns its httpx client and closes it in `close()` (or on leaving a
+    `with` block); one you pass in stays yours to close.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._transport = SyncTransport(api_key, base_url, timeout, http_client)
+        send = self._transport.send
+        self.messages = Messages(send)
+        self.phone_numbers = PhoneNumbers(send)
+        self.verify = Verify(send)
+        self.consents = Consents(send)
+        self.consent_batches = ConsentBatches(send)
+        self.opt_in_confirmations = OptInConfirmations(send)
+        self.webhooks = Webhooks(send)
+        self.emails = Emails(send)
+        self.batch = Batch(send)
+        self.domains = Domains(send)
+        self.suppressions = Suppressions(send)
+        self.templates = Templates(send)
+        self.toll_free_verifications = TollFreeVerifications(send)
+        self.business_verification = BusinessVerificationResource(send)
+        self.auto_topup = AutoTopupResource(send)
+        self.topup_cap_requests = TopupCapRequests(send)
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> Honkio:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+class AsyncHonkio:
+    """The asynchronous HonkIO client. Same resources and arguments as `Honkio`, every call awaited."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._transport = AsyncTransport(api_key, base_url, timeout, http_client)
+        send = self._transport.send
+        self.messages = AsyncMessages(send)
+        self.phone_numbers = AsyncPhoneNumbers(send)
+        self.verify = AsyncVerify(send)
+        self.consents = AsyncConsents(send)
+        self.consent_batches = AsyncConsentBatches(send)
+        self.opt_in_confirmations = AsyncOptInConfirmations(send)
+        self.webhooks = AsyncWebhooks(send)
+        self.emails = AsyncEmails(send)
+        self.batch = AsyncBatch(send)
+        self.domains = AsyncDomains(send)
+        self.suppressions = AsyncSuppressions(send)
+        self.templates = AsyncTemplates(send)
+        self.toll_free_verifications = AsyncTollFreeVerifications(send)
+        self.business_verification = AsyncBusinessVerificationResource(send)
+        self.auto_topup = AsyncAutoTopupResource(send)
+        self.topup_cap_requests = AsyncTopupCapRequests(send)
+
+    async def aclose(self) -> None:
+        await self._transport.aclose()
+
+    async def __aenter__(self) -> AsyncHonkio:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.aclose()

honkio/_core.py

@@ -0,0 +1,280 @@
+"""Request description, path filling and response parsing, shared by the sync and async clients."""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import date, datetime, timezone
+from typing import Any, NoReturn
+from urllib.parse import quote
+
+from ._errors import ApiError, InvalidArgumentError, error_for_status
+from ._version import __version__
+
+DEFAULT_BASE_URL = "https://api.honkio.ca"
+DEFAULT_TIMEOUT = 30.0
+USER_AGENT = f"honkio-python/{__version__}"
+
+# The error envelope every API error carries. Anything else beside it is route-specific data.
+ENVELOPE = {"code", "message", "messageEn", "messageFr", "statusCode", "details"}
+
+
+@dataclass(frozen=True)
+class Request:
+    """One API call, described once and executed by either transport."""
+
+    method: str
+    path: str  # a template such as "/v1/email-domains/{id}"
+    path_params: Mapping[str, str] = field(default_factory=dict)
+    query: list[tuple[str, str]] = field(default_factory=list)
+    body: dict[str, Any] | list[Any] | None = None
+    idempotency_key: str | None = None
+    binary: bool = False
+
+
+def fill_path(template: str, params: Mapping[str, str]) -> str:
+    """Fill `{name}` placeholders, one encoded segment each.
+
+    An empty, "." or ".." value is refused: an HTTP client would collapse
+    `/v1/email-domains/..` into `/v1/`, so the request would reach a different resource.
+    """
+
+    def fill(match: re.Match[str]) -> str:
+        name = match.group(1)
+        value = params.get(name)
+        if not isinstance(value, str) or value in ("", ".", ".."):
+            raise InvalidArgumentError(
+                f'The identifier "{name}" for {template} must be a non-empty string other than "." or ".."; '
+                "nothing was sent."
+            )
+        return quote(value, safe="")
+
+    return re.sub(r"\{(\w+)\}", fill, template)
+
+
+def api_name(key: str) -> str:
+    """`from_` is a Python keyword workaround; the API's field is `from`."""
+    return "from" if key == "from_" else key
+
+
+class NotGiven:
+    """The type of NOT_GIVEN: an optional argument the caller left out (so it is not sent).
+
+    `None` is a value, sent as JSON null in a body; this is how an argument is told apart from
+    "set to null". Falsy, so `if not value` treats it as absent.
+    """
+
+    _instance: NotGiven | None = None
+
+    def __new__(cls) -> NotGiven:
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __bool__(self) -> bool:
+        return False
+
+    def __repr__(self) -> str:
+        return "NOT_GIVEN"
+
+
+NOT_GIVEN = NotGiven()
+
+
+# Fields the API declares as `format: date` (YYYY-MM-DD); every other datetime is a date-time.
+DATE_FIELDS = frozenset({"date_from", "date_to", "last_transaction_date"})
+
+
+def format_datetime(value: datetime) -> str:
+    """An aware datetime in UTC with a `Z` suffix, as the API's date-time fields require.
+
+    A naive datetime is refused: guessing a time zone would schedule a send at the wrong hour.
+    """
+    if value.tzinfo is None or value.utcoffset() is None:
+        raise InvalidArgumentError(
+            "A datetime must be timezone-aware (for example datetime.now(timezone.utc)); nothing was sent."
+        )
+    return value.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def format_date(value: date) -> str:
+    """YYYY-MM-DD. A datetime is converted to its UTC date; a naive one is refused."""
+    if isinstance(value, datetime):
+        if value.tzinfo is None or value.utcoffset() is None:
+            raise InvalidArgumentError(
+                "A datetime passed for a date field must be timezone-aware; pass a date or a "
+                "YYYY-MM-DD string instead. Nothing was sent."
+            )
+        return value.astimezone(timezone.utc).date().isoformat()
+    return value.isoformat()
+
+
+def _convert(key: str, value: Any) -> Any:
+    if key in DATE_FIELDS and isinstance(value, date):
+        return format_date(value)
+    if isinstance(value, datetime):
+        return format_datetime(value)
+    if isinstance(value, date):
+        return value.isoformat()
+    return value
+
+
+def build_body(fields: Mapping[str, Any]) -> dict[str, Any]:
+    """Omits NOT_GIVEN; an explicit None is kept and sent as null."""
+    return {
+        api_name(key): _convert(key, value)
+        for key, value in fields.items()
+        if not isinstance(value, NotGiven)
+    }
+
+
+def _format_query_value(key: str, value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    value = _convert(key, value)
+    return value if isinstance(value, str) else str(value)
+
+
+def build_query(fields: Mapping[str, Any]) -> list[tuple[str, str]]:
+    pairs: list[tuple[str, str]] = []
+    for key, value in fields.items():
+        if value is None or isinstance(value, NotGiven):
+            continue
+        name = api_name(key)
+        if isinstance(value, (list, tuple)):
+            pairs.extend((name, _format_query_value(key, item)) for item in value)
+        else:
+            pairs.append((name, _format_query_value(key, value)))
+    return pairs
+
+
+def build_headers(api_key: str, request: Request) -> dict[str, str]:
+    headers = {"Authorization": f"Bearer {api_key}", "User-Agent": USER_AGENT}
+    if not request.binary:
+        headers["Accept"] = "application/json"
+    if request.body is not None:
+        headers["Content-Type"] = "application/json"
+    if request.idempotency_key:
+        headers["Idempotency-Key"] = request.idempotency_key
+    return headers
+
+
+def encode_body(request: Request) -> bytes | None:
+    if request.body is None:
+        return None
+    return json.dumps(request.body, separators=(",", ":"), default=_json_default).encode("utf-8")
+
+
+def _json_default(value: Any) -> Any:
+    if isinstance(value, datetime):
+        return format_datetime(value)
+    if isinstance(value, date):
+        return value.isoformat()
+    raise TypeError(f"Object of type {type(value).__name__} is not JSON serializable")
+
+
+def parse_response(status: int, text: str, location: str | None = None) -> Any:
+    """A port of the Node SDK's parseResponse: 2xx returns the decoded body, anything else raises."""
+    body: Any = None
+    is_json = text == ""
+    if text:
+        try:
+            body, is_json = json.loads(text), True
+        except ValueError:
+            is_json = False
+    if 200 <= status < 300:
+        if not is_json:
+            raise ApiError("application_error", "The API answered with a body that is not JSON.", status)
+        return body
+    raise_for_error(status, text, body, is_json, location)
+
+
+def raise_for_error(
+    status: int, text: str, body: Any, is_json: bool, location: str | None = None
+) -> NoReturn:
+    if 300 <= status < 400 and location:
+        # httpx does not follow redirects by default; say where the API sent us.
+        raise error_for_status(
+            "application_error",
+            f"HTTP {status}: redirected to {location}. Check base_url; the SDK does not follow redirects.",
+            status,
+            {"location": location},
+        )
+    if not is_json or not isinstance(body, dict):
+        raise error_for_status("application_error", text[:200] or f"HTTP {status}", status, None)
+    code = body["code"] if isinstance(body.get("code"), str) else "application_error"
+    message = body["message"] if isinstance(body.get("message"), str) else f"HTTP {status}"
+    details = body.get("details")
+    if "details" not in body and isinstance(body.get("code"), str):
+        # A real API error (it has a code) may carry data beside the envelope, such as
+        # attempts_remaining on VERIFICATION_INVALID_CODE. Without this it would be lost.
+        extra = {k: v for k, v in body.items() if k not in ENVELOPE}
+        details = extra or None
+    raise error_for_status(code, message, status, details)
+
+
+def parse_binary_response(status: int, content: bytes, location: str | None = None) -> bytes:
+    """2xx returns the bytes as they are; an error status is the API's usual JSON envelope."""
+    if 200 <= status < 300:
+        return content
+    text = content.decode("utf-8", errors="replace")
+    body: Any = None
+    is_json = False
+    try:
+        body, is_json = json.loads(text), True
+    except ValueError:
+        pass
+    raise_for_error(status, text, body, is_json, location)
+
+
+def resolve_url(base_url: str, request: Request) -> str:
+    return base_url.rstrip("/") + fill_path(request.path, request.path_params)
+
+
+@dataclass(frozen=True)
+class Subject:
+    kind: str  # "phone" or "email"
+    value: str
+
+    def as_fields(self) -> dict[str, str]:
+        return {"phone_number" if self.kind == "phone" else "email_address": self.value}
+
+
+def one_subject(phone_number: str | None, email_address: str | None) -> Subject:
+    """Exactly one of phone_number or email_address, as the API requires. An empty string counts as not given."""
+    phone = bool(phone_number)
+    email = bool(email_address)
+    if phone == email:
+        raise InvalidArgumentError("Pass exactly one of phone_number or email_address; nothing was sent.")
+    if phone:
+        return Subject("phone", str(phone_number))
+    return Subject("email", str(email_address))
+
+
+def join_area_codes(area_codes: str | list[str] | NotGiven | None) -> str | NotGiven | None:
+    """The API takes one comma-separated value; a repeated key would not be read as a list."""
+    if isinstance(area_codes, list):
+        return ",".join(area_codes) or None
+    return area_codes
+
+
+def batch_body(
+    emails: list[dict[str, Any]] | None,
+    recipients: list[dict[str, Any]] | None,
+    shared: Mapping[str, Any],
+) -> dict[str, Any] | list[Any]:
+    """The batch endpoint takes a list of emails, or one message with a `recipients` list. Never both.
+
+    The caller's own email dicts go out exactly as written (write `"from"`, not `from_`).
+    """
+    if (emails is None) == (recipients is None):
+        raise InvalidArgumentError("Pass exactly one of emails or recipients; nothing was sent.")
+    if emails is not None:
+        if any(not isinstance(value, NotGiven) for value in shared.values()):
+            raise InvalidArgumentError(
+                "Fields beside `emails` are ignored by the API. Put them on each email, or use `recipients`."
+            )
+        return list(emails)
+    return {**build_body(shared), "recipients": recipients}

honkio/_endpoints.py

@@ -0,0 +1,93 @@
+"""Every route the SDK calls. tests/test_spec_contract.py checks each against the OpenAPI snapshot."""
+
+from __future__ import annotations
+
+from typing import NamedTuple
+
+
+class Endpoint(NamedTuple):
+    resource: str
+    method: str
+    http_method: str
+    path: str
+
+
+ENDPOINTS: tuple[Endpoint, ...] = (
+    Endpoint("messages", "send", "POST", "/v1/messages"),
+    Endpoint("messages", "get", "GET", "/v1/messages/{id}"),
+    Endpoint("messages", "list", "GET", "/v1/messages"),
+    Endpoint("phone_numbers", "area_codes", "GET", "/v1/phone-numbers/area-codes"),
+    Endpoint("phone_numbers", "search", "GET", "/v1/phone-numbers/search"),
+    Endpoint("phone_numbers", "provision", "POST", "/v1/phone-numbers"),
+    Endpoint("phone_numbers", "list", "GET", "/v1/phone-numbers"),
+    Endpoint("phone_numbers", "get", "GET", "/v1/phone-numbers/{id}"),
+    Endpoint("phone_numbers", "release", "DELETE", "/v1/phone-numbers/{id}"),
+    Endpoint("verify", "start", "POST", "/v1/verify"),
+    Endpoint("verify", "check", "POST", "/v1/verify/{id}/check"),
+    Endpoint("verify", "get", "GET", "/v1/verify/{id}"),
+    Endpoint("verify", "list", "GET", "/v1/verify"),
+    Endpoint("consents", "create", "POST", "/v1/compliance/consents"),
+    Endpoint("consents", "list", "GET", "/v1/compliance/consents"),
+    Endpoint("consents", "record_batch", "POST", "/v1/compliance/consents/batch"),
+    Endpoint("consents", "check", "GET", "/v1/compliance/consents/check"),
+    Endpoint("consents", "revoke", "DELETE", "/v1/compliance/consents/{phone}"),
+    Endpoint("consents", "revoke", "DELETE", "/v1/compliance/consents/email/{address}"),
+    Endpoint("consent_batches", "list", "GET", "/v1/compliance/consent-batches"),
+    Endpoint("consent_batches", "get", "GET", "/v1/compliance/consent-batches/{id}"),
+    Endpoint("opt_in_confirmations", "send", "POST", "/v1/compliance/opt-in-confirmations"),
+    Endpoint("opt_in_confirmations", "list", "GET", "/v1/compliance/opt-in-confirmations"),
+    Endpoint("webhooks", "create", "POST", "/v1/webhooks"),
+    Endpoint("webhooks", "list", "GET", "/v1/webhooks"),
+    Endpoint("webhooks", "get", "GET", "/v1/webhooks/{id}"),
+    Endpoint("webhooks", "update", "PATCH", "/v1/webhooks/{id}"),
+    Endpoint("webhooks", "remove", "DELETE", "/v1/webhooks/{id}"),
+    Endpoint("webhooks", "deliveries", "GET", "/v1/webhooks/{id}/deliveries"),
+    Endpoint("webhooks", "dead_letters", "GET", "/v1/webhooks/{id}/dead-letters"),
+    Endpoint("webhooks", "replay", "POST", "/v1/webhooks/dead-letters/{dlid}/replay"),
+    Endpoint("webhooks", "discard", "DELETE", "/v1/webhooks/dead-letters/{dlid}"),
+    Endpoint("webhooks", "reactivate", "POST", "/v1/webhooks/{id}/reactivate"),
+    Endpoint("webhooks", "rotate_secret", "POST", "/v1/webhooks/{id}/rotate-secret"),
+    Endpoint("emails", "send", "POST", "/v1/emails"),
+    Endpoint("emails", "get", "GET", "/v1/emails/{id}"),
+    Endpoint("emails", "list", "GET", "/v1/emails"),
+    Endpoint("emails", "update", "PATCH", "/v1/emails/{id}"),
+    Endpoint("emails", "cancel", "DELETE", "/v1/emails/{id}"),
+    Endpoint("emails.received", "list", "GET", "/v1/emails/received"),
+    Endpoint("emails.received", "address", "GET", "/v1/emails/received/address"),
+    Endpoint("emails.received", "set_address_enabled", "PATCH", "/v1/emails/received/address"),
+    Endpoint("emails.received", "get", "GET", "/v1/emails/received/{id}"),
+    Endpoint("emails.received", "raw", "GET", "/v1/emails/received/{id}/raw"),
+    Endpoint("emails.received", "attachment", "GET", "/v1/emails/received/{id}/attachments/{attachmentId}"),
+    Endpoint("emails.received", "simulate", "POST", "/v1/emails/received/simulate"),
+    Endpoint("batch", "send", "POST", "/v1/emails/batch"),
+    Endpoint("domains", "create", "POST", "/v1/email-domains"),
+    Endpoint("domains", "get", "GET", "/v1/email-domains/{id}"),
+    Endpoint("domains", "list", "GET", "/v1/email-domains"),
+    Endpoint("domains", "update", "PATCH", "/v1/email-domains/{id}"),
+    Endpoint("domains", "verify", "POST", "/v1/email-domains/{id}/verify"),
+    Endpoint("domains", "remove", "DELETE", "/v1/email-domains/{id}"),
+    Endpoint("suppressions", "create", "POST", "/v1/email-suppressions"),
+    Endpoint("suppressions", "list", "GET", "/v1/email-suppressions"),
+    Endpoint("suppressions", "remove", "DELETE", "/v1/email-suppressions/{address}"),
+    Endpoint("templates", "create", "POST", "/v1/email-templates"),
+    Endpoint("templates", "get", "GET", "/v1/email-templates/{idOrAlias}"),
+    Endpoint("templates", "list", "GET", "/v1/email-templates"),
+    Endpoint("templates", "update", "PATCH", "/v1/email-templates/{idOrAlias}"),
+    Endpoint("templates", "publish", "POST", "/v1/email-templates/{idOrAlias}/publish"),
+    Endpoint("templates", "rollback", "POST", "/v1/email-templates/{idOrAlias}/rollback"),
+    Endpoint("templates", "versions", "GET", "/v1/email-templates/{idOrAlias}/versions"),
+    Endpoint("templates", "remove", "DELETE", "/v1/email-templates/{idOrAlias}"),
+    Endpoint("toll_free_verifications", "options", "GET", "/v1/toll-free-verifications/options"),
+    Endpoint("toll_free_verifications", "create", "POST", "/v1/toll-free-verifications"),
+    Endpoint("toll_free_verifications", "update", "PATCH", "/v1/toll-free-verifications/{id}"),
+    Endpoint("toll_free_verifications", "submit", "POST", "/v1/toll-free-verifications/{id}/submit"),
+    Endpoint("toll_free_verifications", "cancel", "DELETE", "/v1/toll-free-verifications/{id}"),
+    Endpoint("toll_free_verifications", "get", "GET", "/v1/toll-free-verifications/{id}"),
+    Endpoint("toll_free_verifications", "list", "GET", "/v1/toll-free-verifications"),
+    Endpoint("business_verification", "get", "GET", "/v1/business-verification"),
+    Endpoint("business_verification", "save", "PUT", "/v1/business-verification"),
+    Endpoint("business_verification", "submit", "POST", "/v1/business-verification/submit"),
+    Endpoint("auto_topup", "get", "GET", "/v1/auto-topup"),
+    Endpoint("topup_cap_requests", "create", "POST", "/v1/account/topup-cap-requests"),
+    Endpoint("topup_cap_requests", "list", "GET", "/v1/account/topup-cap-requests"),
+)

honkio/_errors.py

@@ -0,0 +1,101 @@
+"""Every exception the SDK raises. Errors are exceptions, not result objects."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class HonkioError(Exception):
+    """Base class for everything this SDK raises."""
+
+
+class ApiError(HonkioError):
+    """The API answered with an error status (or with a body the SDK cannot read)."""
+
+    def __init__(self, code: str, message: str, status_code: int, details: Any | None = None) -> None:
+        super().__init__(f"{code}: {message} (HTTP {status_code})")
+        self.code = code
+        self.message = message
+        self.status_code = status_code
+        self.details = details
+
+    def __reduce__(self) -> tuple[Any, ...]:
+        # Exception pickles by re-calling the class with `self.args`, which is the one formatted
+        # message here; rebuild from the real constructor arguments instead.
+        return (type(self), (self.code, self.message, self.status_code, self.details))
+
+
+class BadRequestError(ApiError):
+    """HTTP 400."""
+
+
+class AuthenticationError(ApiError):
+    """HTTP 401."""
+
+
+class PaymentRequiredError(ApiError):
+    """HTTP 402."""
+
+
+class PermissionDeniedError(ApiError):
+    """HTTP 403."""
+
+
+class NotFoundError(ApiError):
+    """HTTP 404."""
+
+
+class ConflictError(ApiError):
+    """HTTP 409."""
+
+
+class UnprocessableEntityError(ApiError):
+    """HTTP 422."""
+
+
+class RateLimitError(ApiError):
+    """HTTP 429."""
+
+
+class UnavailableForLegalReasonsError(ApiError):
+    """HTTP 451."""
+
+
+class InternalServerError(ApiError):
+    """HTTP 500 and above."""
+
+
+class APIConnectionError(HonkioError):
+    """The request never produced a response (DNS, refused connection, reset)."""
+
+
+class APITimeoutError(APIConnectionError):
+    """The request timed out. A send may or may not have gone through: retry with an idempotency key."""
+
+
+class InvalidArgumentError(HonkioError, ValueError):
+    """A call was refused before anything was sent."""
+
+
+class InvalidSignatureError(HonkioError):
+    """A webhook failed signature verification."""
+
+
+_BY_STATUS: dict[int, type[ApiError]] = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    402: PaymentRequiredError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: UnprocessableEntityError,
+    429: RateLimitError,
+    451: UnavailableForLegalReasonsError,
+}
+
+
+def error_for_status(code: str, message: str, status: int, details: Any | None) -> ApiError:
+    cls = _BY_STATUS.get(status)
+    if cls is None:
+        cls = InternalServerError if status >= 500 else ApiError
+    return cls(code, message, status, details)