agentscore-py 2.0.2__tar.gz → 2.1.0__tar.gz

{agentscore_py-2.0.2 → agentscore_py-2.1.0}/.claude/CLAUDE.md

@@ -9,13 +9,20 @@ Two identity paths: `X-Wallet-Address` (wallet-based) and `X-Operator-Token` (cr
 ## Methods (sync + async)
 
 - `get_reputation` / `aget_reputation` — cached reputation lookup (free)
-- `assess` / `aassess` — identity gate with policy (paid). Accepts `operator_token` for non-wallet agents. Response includes `linked_wallets[]` and `resolved_operator`.
+- `assess` / `aassess` — identity gate with policy (paid). Accepts `operator_token` for non-wallet agents. Response includes `linked_wallets[]` and `resolved_operator`. Optional `resolve_signer: { address, network }` opts into server-side wallet-signer-match — the response then carries a `signer_match` block describing whether the supplied signer wallet resolves to the same operator as the claimed `address`.
 - `create_session` / `acreate_session` — create verification session. Returns `agent_memory` + `next_steps`.
 - `poll_session` / `apoll_session` — poll session status, returns credential when verified, plus `next_steps.action`.
 - `create_credential` / `acreate_credential` — create operator credential (24h TTL default). Response includes `agent_memory`.
 - `list_credentials` / `alist_credentials` — list active credentials
 - `revoke_credential` / `arevoke_credential` — revoke a credential
 - `associate_wallet` / `aassociate_wallet` — report a signer wallet seen paying under a credential. Accepts optional `idempotency_key` (payment intent id / tx hash) so retries don't inflate transaction_count.
+- `telemetry_signer_match` / `atelemetry_signer_match` — fire-and-forget POST to `/v1/telemetry/signer-match`; commerce gate uses this to report `pass` / `wallet_signer_mismatch` / `wallet_auth_requires_wallet_signing` verdicts.
+
+## Errors + observability
+
+Typed error subclasses of `AgentScoreError` so callers can `except` on the specific class without parsing `err.code`: `PaymentRequiredError` (402), `TokenExpiredError` (401 token_expired — exposes parsed `verify_url` / `session_id` / `poll_secret` / `poll_url` / `next_steps` / `agent_memory` instance attributes), `InvalidCredentialError` (401 invalid_credential), `QuotaExceededError` (429 quota_exceeded — don't retry), `RateLimitedError` (429 rate_limited — retry after Retry-After), `TimeoutError` (httpx.TimeoutException — note: subclasses `AgentScoreError`, not the builtin; import explicitly from `agentscore.errors` to disambiguate). All non-timeout `httpx.HTTPError` (ConnectError, ProtocolError, NetworkError, etc.) wrap to `AgentScoreError(code="network_error", status_code=0)` for parity with node-sdk.
+
+`assess()` / `aassess()` responses include an optional `quota` field captured from `X-Quota-Limit` / `X-Quota-Used` / `X-Quota-Reset` response headers, so callers can monitor approach-to-cap proactively before hitting 429.
 
 ## Architecture
 

{agentscore_py-2.0.2 → agentscore_py-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentscore-py
-Version: 2.0.2
+Version: 2.1.0
 Summary: Python client for the AgentScore APIs
 Project-URL: Homepage, https://agentscore.sh
 Project-URL: Repository, https://github.com/agentscore/python-sdk
@@ -170,18 +170,60 @@ except AgentScoreError as e:
     print(e.code, e.status_code, str(e))
 ```
 
-`AgentScoreError.details` carries the rest of the response body — `verify_url`, `linked_wallets`, `claimed_operator`, `actual_signer`, `expected_signer`, `reasons`, `agent_memory` — so callers can branch on granular denial codes without re-parsing:
+`AgentScoreError.details` carries the rest of the response body — `verify_url`, `linked_wallets`, `claimed_operator`, `actual_signer`, `expected_signer`, `reasons`, `agent_memory` — so callers can branch on granular denial codes without re-parsing.
+
+### Typed error classes
+
+For status-code-specific recovery, the SDK raises typed subclasses of `AgentScoreError`. All inherit from `AgentScoreError` so existing `except AgentScoreError` still catches them.
+
+| Class | Triggered by | What it adds |
+|---|---|---|
+| `PaymentRequiredError` | HTTP 402 | The endpoint is not enabled for this account |
+| `TokenExpiredError` | HTTP 401 with `error.code = "token_expired"` | Parsed body fields on the instance: `verify_url`, `session_id`, `poll_secret`, `poll_url`, `next_steps`, `agent_memory` — recover without re-parsing `details` |
+| `InvalidCredentialError` | HTTP 401 with `error.code = "invalid_credential"` | Permanent — switch tokens or restart |
+| `QuotaExceededError` | HTTP 429 with `error.code = "quota_exceeded"` | Account-level cap reached; don't retry |
+| `RateLimitedError` | HTTP 429 with `error.code = "rate_limited"` | Per-second sliding-window cap; retry after `Retry-After` |
+| `TimeoutError` | `httpx.TimeoutException` (connect/read/write/pool timeout) | Distinct from generic network errors. Note: subclasses `AgentScoreError`, **not** the builtin `TimeoutError` — import explicitly from `agentscore.errors` to disambiguate. |
+
+All non-timeout `httpx.HTTPError` (ConnectError, ProtocolError, NetworkError, etc.) are wrapped as `AgentScoreError(code="network_error", status_code=0)`.
 
 ```python
+from agentscore import (
+    AgentScore, AgentScoreError, TokenExpiredError, QuotaExceededError,
+)
+from agentscore.errors import TimeoutError as AgentScoreTimeoutError
+
 try:
     client.assess("0xabc...", policy={"require_kyc": True})
+except TokenExpiredError as e:
+    print("Verify at:", e.verify_url, "poll with:", e.poll_secret)
+except QuotaExceededError as e:
+    print("Account quota reached — surface to user; don't retry.")
+except AgentScoreTimeoutError:
+    print("Network timeout — retry with backoff.")
 except AgentScoreError as e:
-    if e.code == "wallet_signer_mismatch":
-        print("Re-sign from one of:", e.details.get("linked_wallets"))
-    elif e.code == "token_expired":
-        print("Verify at:", e.details.get("verify_url"))
+    print(e.code, e.message)
+```
+
+## Quota observability
+
+`assess()` (and `aassess()`) responses include an optional `quota` field captured from `X-Quota-Limit` / `X-Quota-Used` / `X-Quota-Reset` response headers. Use it to monitor approach-to-cap proactively (warn at 80%, alert at 95%) before a 429:
+
+```python
+result = client.assess("0xabc...", policy={"require_kyc": True})
+quota = result.get("quota")
+if quota and quota["limit"] and quota["used"]:
+    pct = (quota["used"] / quota["limit"]) * 100
+    if pct > 80:
+        print(f"AgentScore quota at {pct:.1f}% — resets {quota['reset']}")
 ```
 
+`quota` is absent when the API doesn't emit the headers (Enterprise / unlimited tiers).
+
+## Telemetry
+
+`telemetry_signer_match(payload)` and `atelemetry_signer_match(payload)` are fire-and-forget POSTs to `/v1/telemetry/signer-match` so AgentScore can track aggregate signer-binding behavior across merchants. Used internally by `agentscore-commerce`'s gate; available directly for custom integrations that perform their own wallet-signer-match checks.
+
 ## Documentation
 
 - [API Reference](https://docs.agentscore.sh)

{agentscore_py-2.0.2 → agentscore_py-2.1.0}/README.md

@@ -147,18 +147,60 @@ except AgentScoreError as e:
     print(e.code, e.status_code, str(e))
 ```
 
-`AgentScoreError.details` carries the rest of the response body — `verify_url`, `linked_wallets`, `claimed_operator`, `actual_signer`, `expected_signer`, `reasons`, `agent_memory` — so callers can branch on granular denial codes without re-parsing:
+`AgentScoreError.details` carries the rest of the response body — `verify_url`, `linked_wallets`, `claimed_operator`, `actual_signer`, `expected_signer`, `reasons`, `agent_memory` — so callers can branch on granular denial codes without re-parsing.
+
+### Typed error classes
+
+For status-code-specific recovery, the SDK raises typed subclasses of `AgentScoreError`. All inherit from `AgentScoreError` so existing `except AgentScoreError` still catches them.
+
+| Class | Triggered by | What it adds |
+|---|---|---|
+| `PaymentRequiredError` | HTTP 402 | The endpoint is not enabled for this account |
+| `TokenExpiredError` | HTTP 401 with `error.code = "token_expired"` | Parsed body fields on the instance: `verify_url`, `session_id`, `poll_secret`, `poll_url`, `next_steps`, `agent_memory` — recover without re-parsing `details` |
+| `InvalidCredentialError` | HTTP 401 with `error.code = "invalid_credential"` | Permanent — switch tokens or restart |
+| `QuotaExceededError` | HTTP 429 with `error.code = "quota_exceeded"` | Account-level cap reached; don't retry |
+| `RateLimitedError` | HTTP 429 with `error.code = "rate_limited"` | Per-second sliding-window cap; retry after `Retry-After` |
+| `TimeoutError` | `httpx.TimeoutException` (connect/read/write/pool timeout) | Distinct from generic network errors. Note: subclasses `AgentScoreError`, **not** the builtin `TimeoutError` — import explicitly from `agentscore.errors` to disambiguate. |
+
+All non-timeout `httpx.HTTPError` (ConnectError, ProtocolError, NetworkError, etc.) are wrapped as `AgentScoreError(code="network_error", status_code=0)`.
 
 ```python
+from agentscore import (
+    AgentScore, AgentScoreError, TokenExpiredError, QuotaExceededError,
+)
+from agentscore.errors import TimeoutError as AgentScoreTimeoutError
+
 try:
     client.assess("0xabc...", policy={"require_kyc": True})
+except TokenExpiredError as e:
+    print("Verify at:", e.verify_url, "poll with:", e.poll_secret)
+except QuotaExceededError as e:
+    print("Account quota reached — surface to user; don't retry.")
+except AgentScoreTimeoutError:
+    print("Network timeout — retry with backoff.")
 except AgentScoreError as e:
-    if e.code == "wallet_signer_mismatch":
-        print("Re-sign from one of:", e.details.get("linked_wallets"))
-    elif e.code == "token_expired":
-        print("Verify at:", e.details.get("verify_url"))
+    print(e.code, e.message)
+```
+
+## Quota observability
+
+`assess()` (and `aassess()`) responses include an optional `quota` field captured from `X-Quota-Limit` / `X-Quota-Used` / `X-Quota-Reset` response headers. Use it to monitor approach-to-cap proactively (warn at 80%, alert at 95%) before a 429:
+
+```python
+result = client.assess("0xabc...", policy={"require_kyc": True})
+quota = result.get("quota")
+if quota and quota["limit"] and quota["used"]:
+    pct = (quota["used"] / quota["limit"]) * 100
+    if pct > 80:
+        print(f"AgentScore quota at {pct:.1f}% — resets {quota['reset']}")
 ```
 
+`quota` is absent when the API doesn't emit the headers (Enterprise / unlimited tiers).
+
+## Telemetry
+
+`telemetry_signer_match(payload)` and `atelemetry_signer_match(payload)` are fire-and-forget POSTs to `/v1/telemetry/signer-match` so AgentScore can track aggregate signer-binding behavior across merchants. Used internally by `agentscore-commerce`'s gate; available directly for custom integrations that perform their own wallet-signer-match checks.
+
 ## Documentation
 
 - [API Reference](https://docs.agentscore.sh)

{agentscore_py-2.0.2 → agentscore_py-2.1.0}/agentscore/__init__.py

@@ -1,7 +1,15 @@
 from importlib.metadata import version as _pkg_version
 
 from agentscore.client import AgentScore
-from agentscore.errors import AgentScoreError
+from agentscore.errors import (
+    AgentScoreError,
+    InvalidCredentialError,
+    PaymentRequiredError,
+    QuotaExceededError,
+    RateLimitedError,
+    TimeoutError,
+    TokenExpiredError,
+)
 from agentscore.test_mode import AGENTSCORE_TEST_ADDRESSES, is_agentscore_test_address
 from agentscore.types import (
     AccountVerification,
@@ -21,12 +29,15 @@ from agentscore.types import (
     Network,
     NextStepsAction,
     OperatorVerification,
+    QuotaInfo,
     Reputation,
     ReputationResponse,
     ReputationStatus,
+    ResolveSigner,
     SessionCreateRequest,
     SessionCreateResponse,
     SessionPollResponse,
+    SignerMatch,
     VerificationLevel,
     WalletAuthRequiresSigningBody,
     WalletSignerMismatchBody,
@@ -52,15 +63,24 @@ __all__ = [
     "DenialCode",
     "EntityType",
     "Grade",
+    "InvalidCredentialError",
     "Network",
     "NextStepsAction",
     "OperatorVerification",
+    "PaymentRequiredError",
+    "QuotaExceededError",
+    "QuotaInfo",
+    "RateLimitedError",
     "Reputation",
     "ReputationResponse",
     "ReputationStatus",
+    "ResolveSigner",
     "SessionCreateRequest",
     "SessionCreateResponse",
     "SessionPollResponse",
+    "SignerMatch",
+    "TimeoutError",
+    "TokenExpiredError",
     "VerificationLevel",
     "WalletAuthRequiresSigningBody",
     "WalletSignerMismatchBody",

{agentscore_py-2.0.2 → agentscore_py-2.1.0}/agentscore/client.py

@@ -8,7 +8,15 @@ from typing import TYPE_CHECKING, Any
 
 import httpx
 
-from agentscore.errors import AgentScoreError
+from agentscore.errors import (
+    AgentScoreError,
+    InvalidCredentialError,
+    PaymentRequiredError,
+    QuotaExceededError,
+    RateLimitedError,
+    TimeoutError,
+    TokenExpiredError,
+)
 
 logger = logging.getLogger("agentscore")
 
@@ -24,6 +32,99 @@ def _retry_after_seconds(response: httpx.Response) -> float:
         return 1.0
 
 
+def _extract_quota(response: httpx.Response) -> dict[str, Any] | None:
+    """Parse ``X-Quota-Limit``, ``X-Quota-Used``, ``X-Quota-Reset`` from response headers.
+
+    Returns ``None`` when none of the three are present (Enterprise / unlimited tiers).
+    Numeric fields fall back to ``None`` if the header is malformed; reset stays as a
+    string ('never' or ISO-8601 timestamp).
+    """
+    headers = response.headers
+    if not hasattr(headers, "get"):
+        return None
+    limit = headers.get("x-quota-limit")
+    used = headers.get("x-quota-used")
+    reset = headers.get("x-quota-reset")
+    if limit is None and used is None and reset is None:
+        return None
+    return {"limit": _parse_quota_number(limit), "used": _parse_quota_number(used), "reset": reset}
+
+
+def _parse_quota_number(raw: str | None) -> int | None:
+    if raw is None:
+        return None
+    try:
+        return int(raw)
+    except (TypeError, ValueError):
+        return None
+
+
+def _do_sync(send_fn: Callable[[], httpx.Response]) -> httpx.Response:
+    """Execute the sync request, wrapping every httpx-layer failure in a typed AgentScoreError.
+
+    ``httpx.TimeoutException`` (and subclasses: ConnectTimeout / ReadTimeout / WriteTimeout /
+    PoolTimeout) becomes our :class:`TimeoutError`. Every other ``httpx.HTTPError`` (ConnectError,
+    NetworkError, ProtocolError, etc.) becomes :class:`AgentScoreError` with ``code='network_error'``
+    and ``status_code=0`` — parity with the node-sdk catch-all.
+    """
+    try:
+        return send_fn()
+    except httpx.TimeoutException as exc:
+        raise TimeoutError(str(exc)) from exc
+    except httpx.HTTPError as exc:
+        raise AgentScoreError("network_error", str(exc), 0) from exc
+
+
+async def _do_async(send_fn: Callable[[], Awaitable[httpx.Response]]) -> httpx.Response:
+    """Async variant of :func:`_do_sync`."""
+    try:
+        return await send_fn()
+    except httpx.TimeoutException as exc:
+        raise TimeoutError(str(exc)) from exc
+    except httpx.HTTPError as exc:
+        raise AgentScoreError("network_error", str(exc), 0) from exc
+
+
+def _build_error_from_response(response: httpx.Response) -> AgentScoreError:
+    """Map a non-2xx ``httpx.Response`` to the right typed :class:`AgentScoreError` subclass.
+
+    Reads the body to extract ``error.code`` for discrimination + the rest for ``details``.
+    Falls through to a generic :class:`AgentScoreError` for codes the SDK doesn't have a
+    dedicated subclass for.
+    """
+    code = "unknown_error"
+    message = response.text
+    details: dict[str, Any] = {}
+
+    try:
+        body = response.json()
+        if isinstance(body, dict):
+            error = body.get("error", {})
+            if isinstance(error, dict):
+                code = error.get("code", code)
+                message = error.get("message", message)
+            # Preserve everything except the parsed `error` block so consumers can read
+            # verify_url, linked_wallets, reasons, etc. for granular denial recovery.
+            details = {k: v for k, v in body.items() if k != "error"}
+    except ValueError:
+        # Body wasn't JSON or didn't have the expected shape — keep defaults.
+        pass
+
+    if response.status_code == 402:
+        return PaymentRequiredError(message, details)
+    if response.status_code == 401:
+        if code == "token_expired":
+            return TokenExpiredError(message, details)
+        if code == "invalid_credential":
+            return InvalidCredentialError(message, details)
+    if response.status_code == 429:
+        if code == "quota_exceeded":
+            return QuotaExceededError(message, details)
+        if code == "rate_limited":
+            return RateLimitedError(message, details)
+    return AgentScoreError(code, message, response.status_code, details)
+
+
 if TYPE_CHECKING:
     from collections.abc import Awaitable, Callable
 
@@ -36,6 +137,7 @@ if TYPE_CHECKING:
         DecisionPolicy,
         Network,
         ReputationResponse,
+        ResolveSigner,
         SessionCreateResponse,
         SessionPollResponse,
     )
@@ -88,48 +190,45 @@ class AgentScore:
 
     def _send_sync(self, send_fn: Callable[[], httpx.Response]) -> Any:
         """Issue a request, retry once on 429 honoring retry-after, then parse."""
-        response = send_fn()
+        response = _do_sync(send_fn)
         if response.status_code == 429:
             time.sleep(_retry_after_seconds(response))
-            response = send_fn()
+            response = _do_sync(send_fn)
         return self._handle_response(response)
 
+    def _send_sync_with_response(self, send_fn: Callable[[], httpx.Response]) -> tuple[Any, httpx.Response]:
+        """Issue a request, retry once on 429, then return ``(parsed_body, response)``.
+
+        Variant of :meth:`_send_sync` that exposes the raw ``httpx.Response`` so callers
+        (e.g. :meth:`assess`) can read response headers like ``X-Quota-*``.
+        """
+        response = _do_sync(send_fn)
+        if response.status_code == 429:
+            time.sleep(_retry_after_seconds(response))
+            response = _do_sync(send_fn)
+        return self._handle_response(response), response
+
     async def _send_async(self, send_fn: Callable[[], Awaitable[httpx.Response]]) -> Any:
         """Async variant of :meth:`_send_sync`."""
-        response = await send_fn()
+        response = await _do_async(send_fn)
         if response.status_code == 429:
             await asyncio.sleep(_retry_after_seconds(response))
-            response = await send_fn()
+            response = await _do_async(send_fn)
         return self._handle_response(response)
 
-    def _handle_response(self, response: httpx.Response) -> Any:
+    async def _send_async_with_response(
+        self, send_fn: Callable[[], Awaitable[httpx.Response]]
+    ) -> tuple[Any, httpx.Response]:
+        """Async variant of :meth:`_send_sync_with_response`."""
+        response = await _do_async(send_fn)
         if response.status_code == 429:
-            retry_after = response.headers.get("retry-after", "1")
-            raise AgentScoreError(
-                code="rate_limited",
-                message=f"Rate limit exceeded. Retry after {retry_after}s",
-                status_code=429,
-            )
+            await asyncio.sleep(_retry_after_seconds(response))
+            response = await _do_async(send_fn)
+        return self._handle_response(response), response
+
+    def _handle_response(self, response: httpx.Response) -> Any:
         if response.status_code >= 400:
-            try:
-                body = response.json()
-                error = body.get("error", {}) if isinstance(body, dict) else {}
-                # Preserve everything except the parsed `error` block so consumers
-                # can read verify_url, linked_wallets, reasons, etc. for granular
-                # denial recovery — exposed via AgentScoreError.details.
-                details = {k: v for k, v in body.items() if k != "error"} if isinstance(body, dict) else {}
-                raise AgentScoreError(
-                    code=error.get("code", "unknown_error"),
-                    message=error.get("message", response.text),
-                    status_code=response.status_code,
-                    details=details,
-                )
-            except ValueError as err:
-                raise AgentScoreError(
-                    code="unknown_error",
-                    message=response.text,
-                    status_code=response.status_code,
-                ) from err
+            raise _build_error_from_response(response)
         try:
             return response.json()
         except ValueError as err:
@@ -156,8 +255,14 @@ class AgentScore:
         refresh: bool | None = None,
         policy: DecisionPolicy | None = None,
         operator_token: str | None = None,
+        resolve_signer: ResolveSigner | None = None,
     ) -> AssessResponse:
-        """Assess a wallet or operator (paid, writes score on-the-fly)."""
+        """Assess a wallet or operator (paid, writes score on-the-fly).
+
+        ``resolve_signer`` opts into server-side wallet-signer-match: when supplied,
+        the API resolves the signer wallet against the claimed ``address`` and emits
+        a ``signer_match`` block on the response. See :class:`ResolveSigner`.
+        """
         body: dict[str, Any] = {}
         if address:
             body["address"] = address
@@ -169,8 +274,14 @@ class AgentScore:
             body["refresh"] = refresh
         if policy is not None:
             body["policy"] = dict(policy)
+        if resolve_signer is not None:
+            body["resolve_signer"] = dict(resolve_signer)
         client = self._get_sync_client()
-        return self._send_sync(lambda: client.post("/v1/assess", json=body))
+        data, response = self._send_sync_with_response(lambda: client.post("/v1/assess", json=body))
+        quota = _extract_quota(response)
+        if quota is not None:
+            data["quota"] = quota
+        return data
 
     def create_session(
         self,
@@ -282,8 +393,13 @@ class AgentScore:
         refresh: bool | None = None,
         policy: DecisionPolicy | None = None,
         operator_token: str | None = None,
+        resolve_signer: ResolveSigner | None = None,
     ) -> AssessResponse:
-        """Assess a wallet or operator (paid, writes score on-the-fly)."""
+        """Assess a wallet or operator (paid, writes score on-the-fly).
+
+        ``resolve_signer`` opts into server-side wallet-signer-match — async mirror of
+        :meth:`assess`.
+        """
         body: dict[str, Any] = {}
         if address:
             body["address"] = address
@@ -295,8 +411,14 @@ class AgentScore:
             body["refresh"] = refresh
         if policy is not None:
             body["policy"] = dict(policy)
+        if resolve_signer is not None:
+            body["resolve_signer"] = dict(resolve_signer)
         client = self._get_async_client()
-        return await self._send_async(lambda: client.post("/v1/assess", json=body))
+        data, response = await self._send_async_with_response(lambda: client.post("/v1/assess", json=body))
+        quota = _extract_quota(response)
+        if quota is not None:
+            data["quota"] = quota
+        return data
 
     async def acreate_session(
         self,
@@ -382,6 +504,27 @@ class AgentScore:
         client = self._get_async_client()
         return await self._send_async(lambda: client.post("/v1/credentials/wallets", json=body))
 
+    def telemetry_signer_match(self, payload: dict[str, Any]) -> None:
+        """Fire-and-forget telemetry — report a wallet-signer-match verdict.
+
+        Used internally by the commerce gate's ``verify_wallet_signer_match`` helper to track
+        aggregate signer-binding behavior across merchants. Does not raise; failures are
+        logged at warning level so persistent telemetry outages are visible in ops logs.
+        """
+        try:
+            client = self._get_sync_client()
+            client.post("/v1/telemetry/signer-match", json=payload)
+        except Exception as err:
+            logger.warning("telemetry_signer_match failed: %s", err)
+
+    async def atelemetry_signer_match(self, payload: dict[str, Any]) -> None:
+        """Async variant of :meth:`telemetry_signer_match`."""
+        try:
+            client = self._get_async_client()
+            await client.post("/v1/telemetry/signer-match", json=payload)
+        except Exception as err:
+            logger.warning("atelemetry_signer_match failed: %s", err)
+
     def close(self):
         if self._sync_client:
             self._sync_client.close()

agentscore_py-2.1.0/agentscore/errors.py

@@ -0,0 +1,97 @@
+from typing import Any
+
+
+class AgentScoreError(Exception):
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        status_code: int,
+        details: dict[str, Any] | None = None,
+    ):
+        super().__init__(message)
+        self.code = code
+        self.status_code = status_code
+        # Response-body fields beyond `error.{code,message}` — e.g. verify_url,
+        # linked_wallets, claimed_operator, actual_signer, reasons. Consumers
+        # branch on these for granular recovery (see the mcp denial-code rendering
+        # in the node sibling for the canonical use). Defaults to {} so callers
+        # constructing this error by hand without a body can omit it.
+        self.details: dict[str, Any] = details or {}
+
+    @property
+    def status(self) -> int:
+        """Alias for ``status_code`` — parity with node-sdk's attribute name.
+
+        Polyglot codebases can use ``err.status`` regardless of which SDK raised the error.
+        """
+        return self.status_code
+
+
+class PaymentRequiredError(AgentScoreError):
+    """HTTP 402 — the endpoint is not enabled for this account."""
+
+    def __init__(self, message: str, details: dict[str, Any] | None = None) -> None:
+        super().__init__("payment_required", message, 402, details)
+
+
+class TokenExpiredError(AgentScoreError):
+    """HTTP 401 with ``error.code = 'token_expired'`` — credential is no longer valid.
+
+    Covers both revoked and TTL-expired credentials; the API deliberately doesn't disclose
+    which. Body carries an auto-minted verification session — exposed here so callers recover
+    without re-parsing ``details``.
+    """
+
+    def __init__(self, message: str, details: dict[str, Any] | None = None) -> None:
+        super().__init__("token_expired", message, 401, details)
+        d = details or {}
+        self.verify_url: str | None = d.get("verify_url") if isinstance(d.get("verify_url"), str) else None
+        self.session_id: str | None = d.get("session_id") if isinstance(d.get("session_id"), str) else None
+        self.poll_secret: str | None = d.get("poll_secret") if isinstance(d.get("poll_secret"), str) else None
+        self.poll_url: str | None = d.get("poll_url") if isinstance(d.get("poll_url"), str) else None
+        self.next_steps: Any = d.get("next_steps")
+        self.agent_memory: Any = d.get("agent_memory")
+
+
+class InvalidCredentialError(AgentScoreError):
+    """HTTP 401 with ``error.code = 'invalid_credential'`` — operator_token doesn't exist.
+
+    Permanent: no auto-session is issued. Caller should switch tokens or restart.
+    """
+
+    def __init__(self, message: str, details: dict[str, Any] | None = None) -> None:
+        super().__init__("invalid_credential", message, 401, details)
+
+
+class QuotaExceededError(AgentScoreError):
+    """HTTP 429 with ``error.code = 'quota_exceeded'`` — account-level cap reached.
+
+    Don't retry; the cap won't lift through retry alone. Distinct from per-second
+    :class:`RateLimitedError`.
+    """
+
+    def __init__(self, message: str, details: dict[str, Any] | None = None) -> None:
+        super().__init__("quota_exceeded", message, 429, details)
+
+
+class RateLimitedError(AgentScoreError):
+    """HTTP 429 with ``error.code = 'rate_limited'`` — per-second sliding-window cap hit.
+
+    Retry after the interval indicated by the ``Retry-After`` header (typically <= 1s).
+    """
+
+    def __init__(self, message: str, details: dict[str, Any] | None = None) -> None:
+        super().__init__("rate_limited", message, 429, details)
+
+
+class TimeoutError(AgentScoreError):
+    """Request timed out at the network layer (``httpx.TimeoutException``).
+
+    Distinct from generic network errors so callers branch on retry vs surface-to-user
+    without parsing message strings. Subclasses :class:`AgentScoreError` (not the builtin
+    ``TimeoutError``) so existing ``except AgentScoreError`` blocks still catch it.
+    """
+
+    def __init__(self, message: str) -> None:
+        super().__init__("timeout", message, 0)