span-panel-api 3.6.2__tar.gz → 3.8.0b1__tar.gz

{span_panel_api-3.6.2 → span_panel_api-3.8.0b1}/CHANGELOG.md

@@ -7,6 +7,37 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 Pre-releases are not listed separately. A beta is a step towards the next public version, so its changes are folded into that version's entry as they land and are described against the **last public release**, never against the beta before it. What one
 beta corrected in an earlier beta does not appear at all: from the point of view of somebody upgrading between released versions, it never happened.
 
+## [Unreleased]
+
+Snapshot fields that held a fabricated constant can now be unknown, and with `span-panel-api-schema-0` and `span-panel-api-schema-1` 1.3.0 or newer the parsers report them as unknown and stop synthesising unoccupied positions.
+
+### Added
+
+- **spanos3/r202639/03 batch 2: reads more of the data this firmware publishes.**
+- **`V2StatusInfo.hardware_version` reports the hardware version string from `GET /api/v2/status`.**
+
+### Changed
+
+- **BREAKING FOR CONSUMERS: `SpanPanelSnapshot.proximity_proven` becomes `bool | None`**, and with `span-panel-api-schema-0` and `span-panel-api-schema-1` 1.3.0 or newer it is always `None`, where it was effectively a constant `True`, because neither MQTT
+  schema publishes a proximity property and the panel's own answer is `V2StatusInfo.proximity_proven`.
+- **BREAKING FOR CONSUMERS: `SpanPanelSnapshot.uptime_s` becomes `int | None`**, and with those parsers it is `None` on a parent/child panel and before a flat panel first reports ready, where it was a constant `0`.
+- **BREAKING FOR CONSUMERS: `SpanCircuitSnapshot.instant_power_update_time_s` and `energy_accum_update_time_s` become `int | None` and default to `None`**, and with those parsers they are `None` until the reading has arrived and always on a parent/child
+  panel, where they were `0`.
+- **BREAKING FOR CONSUMERS: `SpanCircuitSnapshot.is_240v` becomes `bool | None`**, and with `span-panel-api-schema-1` 1.4.0 or newer it is `None` where the pole count is unpublished.
+- **BREAKING FOR CONSUMERS: `SpanPanelSnapshot.lugs_at_service_entrance` becomes `bool | None`**, and with `span-panel-api-schema-1` 1.4.0 or newer it is `None` while the upstream lugs declare their feed but leave it unpublished.
+- **The `schema-0` extra requires `span-panel-api-schema-0` 1.3.0 or newer and the `schema-1` extra requires `span-panel-api-schema-1` 1.4.0 or newer**, the adapters that report these values as unknown; schema-1 1.4.0 also fills the snapshot fields this
+  release adds.
+
+### Removed
+
+- **BREAKING: with `span-panel-api-schema-0` and `span-panel-api-schema-1` 1.3.0 or newer, snapshots no longer include synthesised `unmapped_tab_N` entries for unoccupied breaker positions, which carried no measured data**, so `SpanPanelSnapshot.circuits`
+  holds only real circuits and `panel_size` alone states the panel's total positions.
+
+### Fixed
+
+- **`V2HomieSchema.types_schema_hash` on data model 1.0 is the panel's published `deviceClassesSchemaHash`, or a hash of `deviceClasses` when none is published, where it was one constant for every such panel**; a flat panel's value is unchanged, and a
+  value stored from 3.6.x differs once on a data model 1.0 panel.
+
 ## [3.6.2]
 
 A reconnect waits for the panel's labels before handing out a snapshot, as connecting always has.
@@ -480,8 +511,7 @@ Everything below is additive. Each field is `None` or empty on a panel that publ
   `MQTT_FULL_REBUILD_AFTER_FAILURES` (3) consecutive failures, or immediately on any `ssl.SSLError`. The previous behavior pinned the panel's CA certificate into the paho client once at `connect()` time and re-used it across all reconnect attempts; if the
   panel rotated its private CA — most plausibly during a firmware upgrade — every subsequent reconnect raised `ssl.SSLCertVerificationError` (caught by the broad `OSError` clause and silently retried) and the bridge could not recover without a config-entry
   reload. The rebuild mirrors what a manual reload does without going through HA's `config_entry` teardown, so entities stay registered and the integration's grace-period logic continues to apply unchanged. The threshold-cadence design (counter reset on
-  every rebuild attempt, success or fail) keeps the recovery path active throughout extended outages — multi-day disconnections recover whenever the panel becomes usable again, including if the CA rotates a second time mid-outage. See
-  `SpanPanel_Docs/span-panel-api/2026-05-17-mqtt-ca-refresh-on-reconnect-design.md` for the full design.
+  every rebuild attempt, success or fail) keeps the recovery path active throughout extended outages — multi-day disconnections recover whenever the panel becomes usable again, including if the CA rotates a second time mid-outage.
 
 ### Added
 

{span_panel_api-3.6.2 → span_panel_api-3.8.0b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: span-panel-api
-Version: 3.6.2
+Version: 3.8.0b1
 Summary: A client library for SPAN Panel API
 Project-URL: Homepage, https://github.com/SpanPanel/span-panel-api
 Project-URL: Issues, https://github.com/SpanPanel/span-panel-api/issues
@@ -20,9 +20,9 @@ Requires-Dist: httpx<1.0,>=0.28.1
 Requires-Dist: paho-mqtt<3.0.0,>=2.0.0
 Requires-Dist: pyyaml>=6.0.0
 Provides-Extra: schema-0
-Requires-Dist: span-panel-api-schema-0>=1.2.0; extra == 'schema-0'
+Requires-Dist: span-panel-api-schema-0>=1.3.0b1; extra == 'schema-0'
 Provides-Extra: schema-1
-Requires-Dist: span-panel-api-schema-1>=1.2.2; extra == 'schema-1'
+Requires-Dist: span-panel-api-schema-1>=1.4.0b1; extra == 'schema-1'
 Description-Content-Type: text/markdown
 
 # SPAN Panel API
@@ -175,8 +175,8 @@ transport-specific classes.
 
 All panel state is represented as immutable, frozen dataclasses:
 
-- **`SpanPanelSnapshot`**: complete panel state. Identity (serial, firmware, vendor, model, hardware version), panel size, main breaker rating, main relay, door and proximity state, uptime, network links with the Wi-Fi SSID and vendor cloud, grid and
-  feedthrough power and energy, grid/DSM state, run configuration, dominant power source, grid islandability, per-leg voltages, power flows, lugs current and whether the lugs are the service entrance, shed policy and forecast. It holds `circuits`,
+- **`SpanPanelSnapshot`**: complete panel state. Identity (serial, firmware, vendor, model, hardware version), panel size, main breaker rating, main relay, door state, connection uptime on a flat panel, network links with the Wi-Fi SSID and vendor cloud,
+  grid and feedthrough power and energy, grid/DSM state, run configuration, dominant power source, grid islandability, per-leg voltages, power flows, lugs current and whether the lugs are the service entrance, shed policy and forecast. It holds `circuits`,
   `battery`, `pv`, `pv_inverters`, `evse`, `mid`, `pcs`, `adopted_devices` and `extension_properties`.
 - **`SpanCircuitSnapshot`**: one circuit. Id, name, relay state and requester, power, energy and their update times, tabs, 240 V, breaker rating, current, priority, user controllability, sheddable / never-backup / always-on flags, device type, relative
   position, PCS management and priority, and the `$target` pending state for relay and priority.
@@ -195,6 +195,9 @@ see the changelog, because `battery.model` changes value for existing flat users
 
 `mid`, `pcs`, `adopted_devices`, `extension_properties` and the per-DER link-health fields exist only under the parent/child schema. They are `None` or empty on a flat panel rather than absent, so a consumer reads the same snapshot type either way.
 
+`uptime_s` and a circuit's update times are the reverse: only the flat parser measures them, and they are `None` under the parent/child schema. Neither schema publishes proximity, so `SpanPanelSnapshot.proximity_proven` is always `None`; the panel's own
+answer is `V2StatusInfo.proximity_proven`, from `GET /api/v2/status`.
+
 ## Usage
 
 ### Factory Pattern (Recommended)

{span_panel_api-3.6.2 → span_panel_api-3.8.0b1}/README.md

@@ -148,8 +148,8 @@ transport-specific classes.
 
 All panel state is represented as immutable, frozen dataclasses:
 
-- **`SpanPanelSnapshot`**: complete panel state. Identity (serial, firmware, vendor, model, hardware version), panel size, main breaker rating, main relay, door and proximity state, uptime, network links with the Wi-Fi SSID and vendor cloud, grid and
-  feedthrough power and energy, grid/DSM state, run configuration, dominant power source, grid islandability, per-leg voltages, power flows, lugs current and whether the lugs are the service entrance, shed policy and forecast. It holds `circuits`,
+- **`SpanPanelSnapshot`**: complete panel state. Identity (serial, firmware, vendor, model, hardware version), panel size, main breaker rating, main relay, door state, connection uptime on a flat panel, network links with the Wi-Fi SSID and vendor cloud,
+  grid and feedthrough power and energy, grid/DSM state, run configuration, dominant power source, grid islandability, per-leg voltages, power flows, lugs current and whether the lugs are the service entrance, shed policy and forecast. It holds `circuits`,
   `battery`, `pv`, `pv_inverters`, `evse`, `mid`, `pcs`, `adopted_devices` and `extension_properties`.
 - **`SpanCircuitSnapshot`**: one circuit. Id, name, relay state and requester, power, energy and their update times, tabs, 240 V, breaker rating, current, priority, user controllability, sheddable / never-backup / always-on flags, device type, relative
   position, PCS management and priority, and the `$target` pending state for relay and priority.
@@ -168,6 +168,9 @@ see the changelog, because `battery.model` changes value for existing flat users
 
 `mid`, `pcs`, `adopted_devices`, `extension_properties` and the per-DER link-health fields exist only under the parent/child schema. They are `None` or empty on a flat panel rather than absent, so a consumer reads the same snapshot type either way.
 
+`uptime_s` and a circuit's update times are the reverse: only the flat parser measures them, and they are `None` under the parent/child schema. Neither schema publishes proximity, so `SpanPanelSnapshot.proximity_proven` is always `None`; the panel's own
+answer is `V2StatusInfo.proximity_proven`, from `GET /api/v2/status`.
+
 ## Usage
 
 ### Factory Pattern (Recommended)

{span_panel_api-3.6.2 → span_panel_api-3.8.0b1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api"
-version = "3.6.2"
+version = "3.8.0b1"
 description = "A client library for SPAN Panel API"
 authors = [
     {name = "SpanPanel"}
@@ -62,11 +62,16 @@ dependencies = [
 # so a 1.1.x adapter is still accepted, but it fills neither `pv_inverters` nor
 # the inverter identity fields 3.6.0 adds. Upgrading through the extra is what
 # brings the adapters that do.
-schema-0 = ["span-panel-api-schema-0>=1.2.0"]
+# Raised to 1.3.0b1 for 3.7.0b1: that adapter reports the unknown values this
+# bootstrap's snapshot fields now accept, and stops synthesising unoccupied positions.
+schema-0 = ["span-panel-api-schema-0>=1.3.0b1"]
 # Raised to 1.2.1 for 3.6.1: that adapter builds the `pv` that `SpanPanelSnapshot.pv` now documents.
 # Raised to 1.2.2 for 3.6.2: the readiness gate every snapshot passes asks that
 # adapter what is still missing, and 1.2.2 restarts its feed grace correctly.
-schema-1 = ["span-panel-api-schema-1>=1.2.2"]
+# Raised to 1.3.0b1 for 3.7.0b1, for the same reason as schema-0's.
+# Raised to 1.4.0b1 for 3.8.0b1: that adapter fills the snapshot fields this
+# bootstrap adds.
+schema-1 = ["span-panel-api-schema-1>=1.4.0b1"]
 
 [project.urls]
 Homepage = "https://github.com/SpanPanel/span-panel-api"
@@ -245,7 +250,11 @@ warn_return_any = true
 warn_unused_configs = true
 disallow_untyped_defs = true
 explicit_package_bases = true
-mypy_path = "src"
+# `tests` because the suite imports its support packages top-level
+# (`from reference_payloads.schema_one import ...`), the way pytest's rootdir puts
+# `tests/` on `sys.path`; the support packages the mypy hook checks resolve the same
+# way here.
+mypy_path = "src:tests"
 # Excluded by name for the reason `[tool.ruff]` gives above: the capture script is
 # checked like the library, and the hand-run tools written before that was expected
 # are not.

{span_panel_api-3.6.2 → span_panel_api-3.8.0b1}/src/span_panel_api/__init__.py

@@ -29,6 +29,7 @@ from .exceptions import (
     SpanPanelError,
     SpanPanelInsufficientPrivilegeError,
     SpanPanelPassphraseUnavailableError,
+    SpanPanelRateLimitError,
     SpanPanelSchemaVersionError,
     SpanPanelServerError,
     SpanPanelStaleDataError,
@@ -41,15 +42,19 @@ from .models import (
     ADOPTION_IDENTITY_NODE,
     ADOPTION_TOPOLOGY_NODE,
     DISCOVERY_NAMESPACE,
+    FEEDS_ROLES,
+    PROTECTION_FUNCTIONS,
     AdoptedDevice,
     AdoptedProperty,
     ControlTarget,
     DiscoveredMetadata,
     ExtensionProperty,
     ExtensionSubject,
+    FeedsRole,
     FieldMetadata,
     HomieSchemaTypes,
     PassphraseRotation,
+    ProtectionFunction,
     SpanBatterySnapshot,
     SpanCircuitSnapshot,
     SpanEvseSnapshot,
@@ -61,6 +66,7 @@ from .models import (
     V2HomieSchema,
     V2StatusInfo,
     is_discovery_path,
+    shared_meter_groups,
 )
 from .mqtt import (
     ControlCommand,
@@ -84,6 +90,7 @@ from .protocol import (
     CircuitControlProtocol,
     ControlInterceptionProtocol,
     EvseControlProtocol,
+    EvseLockControlProtocol,
     PanelCapability,
     PanelControlProtocol,
     SpanPanelClientProtocol,
@@ -106,6 +113,9 @@ __all__ = [  # noqa: RUF022
     # snapshot rather than by its arguments -- a device the adapter models
     # produces no AdoptedDevice and so cannot be addressed through it.
     "AdoptedControlProtocol",
+    # A charger's connector lock, authorised by `SpanEvseSnapshot.lock_control`.
+    # A protocol of its own so `EvseControlProtocol`'s implementers are unchanged.
+    "EvseLockControlProtocol",
     # Added 2026-08-25 (3.1.0): one veto/observe point for every control
     # command. A protocol of its own rather than a member on the four control
     # protocols, which would break their implementers a second time in one
@@ -145,6 +155,16 @@ __all__ = [  # noqa: RUF022
     "SpanPVSnapshot",
     "SpanPanelSnapshot",
     "SpanPcsSnapshot",
+    # What a circuit's `connection/feeds-role` declares, read into
+    # `SpanCircuitSnapshot.feeds_role`.
+    "FEEDS_ROLES",
+    "FeedsRole",
+    # What a circuit's `breaker/protection-functions` lists, read into
+    # `SpanCircuitSnapshot.protection_functions`.
+    "PROTECTION_FUNCTIONS",
+    "ProtectionFunction",
+    # The circuits one meter measures, from `SpanCircuitSnapshot.meter_shared_with`.
+    "shared_meter_groups",
     # Factory
     "create_span_client",
     # Detection
@@ -216,6 +236,10 @@ __all__ = [  # noqa: RUF022
     # keep their meaning; deliberately not a SpanPanelAuthError, because the
     # passphrase the user supplied may be correct.
     "SpanPanelPassphraseUnavailableError",
+    # Registration refused with HTTP 429, carrying the panel's `Retry-After` in
+    # seconds. A subclass of SpanPanelAPIError, so existing except clauses keep
+    # their meaning; not a SpanPanelAuthError, because no credential was judged.
+    "SpanPanelRateLimitError",
     "SpanPanelServerError",
     "SpanPanelStaleDataError",
     # Added 2026-08-31 (3.4.0): a bootstrap REST call that failed verification

{span_panel_api-3.6.2 → span_panel_api-3.8.0b1}/src/span_panel_api/auth.py

@@ -9,10 +9,13 @@ client (which only covers v1 endpoints).
 from __future__ import annotations
 
 import asyncio
-from collections.abc import Collection
+from collections.abc import Collection, Mapping
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
 import hashlib
 import json
 import logging
+import math
 import ssl
 import uuid
 
@@ -24,6 +27,7 @@ from .exceptions import (
     SpanPanelAuthError,
     SpanPanelInsufficientPrivilegeError,
     SpanPanelPassphraseUnavailableError,
+    SpanPanelRateLimitError,
     SpanPanelServerError,
 )
 from .models import HomieSchemaTypes, PassphraseRotation, V2AuthResponse, V2HomieSchema, V2StatusInfo
@@ -216,21 +220,37 @@ CA_CERT_MAX_ATTEMPTS = 5
 CA_CERT_BACKOFF_S = 1.5
 
 
-def _retry_delay(retry_after: str | None, attempt: int, backoff_s: float) -> float:
-    """Return how long to wait before retrying a rate-limited request.
+def _retry_after_s(retry_after: str | None, now: datetime) -> float | None:
+    """The wait a ``Retry-After`` header asks for, in seconds, or None if it asks for none.
 
-    Prefers the panel's ``Retry-After`` header (delta-seconds form) and falls
-    back to exponential backoff. Malformed or negative values fall back too,
-    so a bad header can never stall or skip the retry.
+    Both forms RFC 9110 allows: delta-seconds, taken as given, and an HTTP-date,
+    taken as the seconds from `now` until then (0.0 once it has passed). A
+    negative, infinite or unparseable value is no answer, so a bad header can
+    never stall or skip a retry.
     """
-    fallback = backoff_s * (2.0 ** (attempt - 1))
     if retry_after is None:
-        return fallback
+        return None
     try:
-        parsed = float(retry_after)
-    except (TypeError, ValueError):
-        return fallback
-    return parsed if parsed >= 0 else fallback
+        seconds = float(retry_after)
+    except ValueError:
+        try:
+            until = parsedate_to_datetime(retry_after)
+        except (TypeError, ValueError):
+            return None
+        if until.tzinfo is None:
+            return None
+        return max((until - now).total_seconds(), 0.0)
+    return seconds if math.isfinite(seconds) and seconds >= 0 else None
+
+
+def _retry_delay(retry_after: str | None, attempt: int, backoff_s: float) -> float:
+    """Return how long to wait before retrying a rate-limited request.
+
+    Prefers the panel's ``Retry-After`` header and falls back to exponential
+    backoff where it gives no usable wait.
+    """
+    parsed = _retry_after_s(retry_after, datetime.now(UTC))
+    return backoff_s * (2.0 ** (attempt - 1)) if parsed is None else parsed
 
 
 async def register_v2(
@@ -276,6 +296,7 @@ async def register_v2(
     Raises:
         SpanPanelAuthError: Invalid passphrase or auth failure
         SpanPanelPassphraseUnavailableError: The panel cannot read its own passphrase
+        SpanPanelRateLimitError: HTTP 429; the panel is limiting registrations. Not retried
         SpanPanelServerError: The panel is not ready to register clients (any 5xx,
             including the 503 it answers before its serial number is known); retryable
         SpanPanelConnectionError: Cannot reach panel
@@ -314,6 +335,16 @@ async def register_v2(
             status_code=reply.status_code,
         )
 
+    if reply.status_code == HTTP_TOO_MANY_REQUESTS:
+        # Not retried: the panel limits registrations per client address, and a
+        # retry here would spend the caller's next attempt on its behalf.
+        _log_auth_failure(reply.endpoint, reply.response, sent)
+        raise SpanPanelRateLimitError(
+            f"Panel is rate-limiting registration (HTTP {reply.status_code})",
+            status_code=reply.status_code,
+            retry_after_s=_retry_after_s(reply.headers.get("retry-after"), datetime.now(UTC)),
+        )
+
     if reply.status_code == 422 and _error_detail(reply.response) == REGISTRATION_UNAVAILABLE_DETAIL:
         # Checked before the general 422 below, which means "credential not
         # accepted". This one is the panel failing to read its own passphrase,
@@ -454,6 +485,32 @@ async def download_ca_cert(
     raise SpanPanelAPIError(f"Failed to download CA cert: HTTP {last_status}")
 
 
+def _schema_hash(data: Mapping[str, object]) -> str:
+    """The schema hash ``V2HomieSchema.types_schema_hash`` reports.
+
+    A parent/child panel publishes its schema as ``deviceClasses``, with its own
+    ``deviceClassesSchemaHash`` over that block, in place of flat firmware's
+    ``types``. Hashing ``types`` there hashed an absent block, so every such
+    panel got one constant key. The published hash is taken as is when it is a
+    non-empty string; otherwise ``deviceClasses`` is hashed here.
+
+    SPAN's public API changelog states that ``deviceClassesSchemaHash`` is
+    computed over the new structure, so it differs from a ``typesSchemaHash``
+    even where the property content is unchanged, and that a cached
+    ``typesSchemaHash`` is not to be compared against it. A key held from a
+    release that hashed ``types`` therefore differs once on such a panel.
+
+    A flat panel's key is exactly what earlier releases computed, so a value
+    stored for a flat panel still matches.
+    """
+    published = data.get("deviceClassesSchemaHash")
+    if isinstance(published, str) and published:
+        return published
+    hashed = data["deviceClasses"] if "deviceClasses" in data else data.get("types", {})
+    canonical = json.dumps(hashed, sort_keys=True)
+    return "sha256:" + hashlib.sha256(canonical.encode()).hexdigest()[:16]
+
+
 async def get_homie_schema(
     host: str,
     timeout: float = 10.0,
@@ -527,15 +584,9 @@ async def get_homie_schema(
             if isinstance(props, dict):
                 types[str(type_name)] = {str(k): v for k, v in props.items()}
 
-    # Compute schema hash from types key names for change detection
-    # The panel provides this implicitly via the firmware version + types structure
-    # We derive a hash for caching; the fixture README documents the expected value
-    types_json = json.dumps(data.get("types", {}), sort_keys=True)
-    schema_hash = "sha256:" + hashlib.sha256(types_json.encode()).hexdigest()[:16]
-
     # Read before anything else interprets the payload. A parent/child response
-    # carries `deviceClasses` where this one reads `types`, so every field below
-    # degrades to empty for such a panel — which is harmless only because this
+    # carries `deviceClasses` where this one reads `types`, so `types` degrades
+    # to empty for such a panel — which is harmless only because this
     # value routes it to a different parser before those fields are used.
     # Absence is the flat signal and must stay distinct from an empty string.
     raw_data_model_version = data.get("dataModelVersion")
@@ -543,7 +594,7 @@ async def get_homie_schema(
 
     return V2HomieSchema(
         firmware_version=str(data.get("firmwareVersion", "")),
-        types_schema_hash=schema_hash,
+        types_schema_hash=_schema_hash(data),
         types=types,
         data_model_version=data_model_version,
     )
@@ -593,8 +644,8 @@ async def rotate_passphrase(
     Raises:
         SpanPanelInsufficientPrivilegeError: HTTP 403; the token is reduced-privilege
         SpanPanelAuthError: HTTP 401 (token invalid or stale) or 412 (no bearer token)
-        SpanPanelServerError: HTTP 5xx. After a 500 the outcome is unknown: the
-            passphrase may or may not have changed.
+        SpanPanelServerError: HTTP 5xx. After a 500 or a 504 the outcome is unknown:
+            the passphrase may or may not have changed.
         SpanPanelConnectionError: Cannot reach panel
         SpanPanelTimeoutError: Request timed out
         SpanPanelAPIError: Unexpected response

{span_panel_api-3.6.2 → span_panel_api-3.8.0b1}/src/span_panel_api/exceptions.py

@@ -68,6 +68,25 @@ class SpanPanelServerError(SpanPanelAPIError):
     """
 
 
+class SpanPanelRateLimitError(SpanPanelAPIError):
+    """The panel is limiting the client's requests and refused this one (HTTP 429).
+
+    Raised by ``register_v2``, which does not retry: the caller decides when to
+    try again. ``retry_after_s`` is the wait the panel asked for, in seconds,
+    from its ``Retry-After`` header: a delta-seconds value as given, an HTTP-date
+    as the seconds until that time. ``None`` when the header is absent or holds
+    neither.
+
+    A `SpanPanelAPIError`, so an existing clause catching that class still
+    catches this, and not a `SpanPanelAuthError`: the credential was never
+    judged.
+    """
+
+    def __init__(self, message: str, status_code: int | None = None, retry_after_s: float | None = None) -> None:
+        super().__init__(message, status_code)
+        self.retry_after_s = retry_after_s
+
+
 class SpanPanelPassphraseUnavailableError(SpanPanelAPIError):
     """The panel cannot read its own passphrase, so it cannot issue broker credentials.