|
| 1 | +# Error Handling and Retry |
| 2 | + |
| 3 | +## Exception Hierarchy |
| 4 | + |
| 5 | +All exceptions inherit from `SpanPanelError`. |
| 6 | + |
| 7 | +```text |
| 8 | +SpanPanelError |
| 9 | +├── SpanPanelAuthError — authentication failures (401, 403) |
| 10 | +├── SpanPanelConnectionError — network errors or unreachable panel |
| 11 | +├── SpanPanelTimeoutError — request timeout |
| 12 | +├── SpanPanelValidationError — invalid input or schema mismatch |
| 13 | +├── SpanPanelAPIError — general API error (catch-all for HTTP errors) |
| 14 | +├── SpanPanelRetriableError — transient server errors (502, 503, 504) |
| 15 | +├── SpanPanelServerError — non-retriable server error (500) |
| 16 | +├── SpanPanelGrpcError — base for Gen3 gRPC errors |
| 17 | +│ └── SpanPanelGrpcConnectionError — Gen3 connection failure |
| 18 | +└── SimulationConfigurationError — invalid simulation config (simulation mode only) |
| 19 | +``` |
| 20 | + |
| 21 | +### Import |
| 22 | + |
| 23 | +```python |
| 24 | +from span_panel_api import ( |
| 25 | + SpanPanelError, |
| 26 | + SpanPanelAuthError, |
| 27 | + SpanPanelConnectionError, |
| 28 | + SpanPanelTimeoutError, |
| 29 | + SpanPanelValidationError, |
| 30 | + SpanPanelAPIError, |
| 31 | + SpanPanelRetriableError, |
| 32 | + SpanPanelServerError, |
| 33 | + SpanPanelGrpcError, |
| 34 | + SpanPanelGrpcConnectionError, |
| 35 | + SimulationConfigurationError, |
| 36 | +) |
| 37 | +``` |
| 38 | + |
| 39 | +## HTTP Error → Exception Mapping (Gen2) |
| 40 | + |
| 41 | +| HTTP Status | Exception | Retriable | Action | |
| 42 | +| ------------------ | ------------------------------ | -------------------- | ------------------------------ | |
| 43 | +| 401, 403 | `SpanPanelAuthError` | Once (after re-auth) | Re-authenticate then retry | |
| 44 | +| 500 | `SpanPanelServerError` | No | Check server; report issue | |
| 45 | +| 502, 503, 504 | `SpanPanelRetriableError` | Yes | Retry with exponential backoff | |
| 46 | +| 404, 400, etc. | `SpanPanelAPIError` | Case-by-case | Check request parameters | |
| 47 | +| Timeout | `SpanPanelTimeoutError` | Yes | Retry with backoff | |
| 48 | +| Validation failure | `SpanPanelValidationError` | No | Fix input data | |
| 49 | +| Simulation config | `SimulationConfigurationError` | No | Fix simulation config file | |
| 50 | + |
| 51 | +The underlying HTTP client is configured with `raise_on_unexpected_status=True`, so unexpected status codes are never silently ignored. |
| 52 | + |
| 53 | +## Handling Errors in Practice |
| 54 | + |
| 55 | +```python |
| 56 | +from span_panel_api import ( |
| 57 | + SpanPanelAuthError, |
| 58 | + SpanPanelRetriableError, |
| 59 | + SpanPanelTimeoutError, |
| 60 | + SpanPanelValidationError, |
| 61 | + SpanPanelAPIError, |
| 62 | +) |
| 63 | + |
| 64 | +async def fetch_circuits(client): |
| 65 | + try: |
| 66 | + return await client.get_circuits() |
| 67 | + except SpanPanelAuthError: |
| 68 | + # Token expired or not yet authenticated — re-auth and retry once |
| 69 | + await client.authenticate("my-app", "My Application") |
| 70 | + return await client.get_circuits() |
| 71 | + except SpanPanelRetriableError as exc: |
| 72 | + # Temporary server overload — let retry logic or coordinator handle this |
| 73 | + logger.warning("Transient server error, will retry: %s", exc) |
| 74 | + raise |
| 75 | + except SpanPanelTimeoutError as exc: |
| 76 | + # Network too slow — retry after backoff |
| 77 | + logger.warning("Request timed out: %s", exc) |
| 78 | + raise |
| 79 | + except SpanPanelValidationError as exc: |
| 80 | + # Unexpected response structure — not retriable |
| 81 | + logger.error("Validation error: %s", exc) |
| 82 | + raise |
| 83 | + except SpanPanelAPIError as exc: |
| 84 | + # Any other API error |
| 85 | + logger.error("API error: %s", exc) |
| 86 | + raise |
| 87 | +``` |
| 88 | + |
| 89 | +## Retry Configuration (Gen2) |
| 90 | + |
| 91 | +Configure retries on the client to handle transient network issues automatically: |
| 92 | + |
| 93 | +```python |
| 94 | +from span_panel_api import SpanPanelClient |
| 95 | + |
| 96 | +client = SpanPanelClient( |
| 97 | + "192.168.1.100", |
| 98 | + timeout=10.0, |
| 99 | + retries=3, # 3 retries → up to 4 total attempts |
| 100 | + retry_timeout=0.5, # initial delay before first retry |
| 101 | + retry_backoff_multiplier=2.0, # delays: 0.5s, 1.0s, 2.0s |
| 102 | +) |
| 103 | +``` |
| 104 | + |
| 105 | +Only `SpanPanelRetriableError` and `SpanPanelTimeoutError` trigger automatic retries. `SpanPanelAuthError` and `SpanPanelValidationError` are not retried automatically. |
| 106 | + |
| 107 | +### Retry Attempt Count |
| 108 | + |
| 109 | +| `retries` | Total attempts | |
| 110 | +| ----------- | -------------- | |
| 111 | +| 0 (default) | 1 | |
| 112 | +| 1 | 2 | |
| 113 | +| 2 | 3 | |
| 114 | +| 3 | 4 | |
| 115 | + |
| 116 | +Settings can be changed at runtime: |
| 117 | + |
| 118 | +```python |
| 119 | +client.retries = 2 |
| 120 | +client.retry_timeout = 1.0 |
| 121 | +client.retry_backoff_multiplier = 1.5 |
| 122 | +``` |
| 123 | + |
| 124 | +## Gen3 gRPC Errors |
| 125 | + |
| 126 | +Gen3 errors use a separate, simpler hierarchy since gRPC does not use HTTP status codes: |
| 127 | + |
| 128 | +```python |
| 129 | +from span_panel_api import SpanPanelGrpcError, SpanPanelGrpcConnectionError |
| 130 | + |
| 131 | +try: |
| 132 | + await client.connect() |
| 133 | + snapshot = await client.get_snapshot() |
| 134 | +except SpanPanelGrpcConnectionError as exc: |
| 135 | + # Panel unreachable or gRPC channel failed |
| 136 | + logger.error("Gen3 connection failed: %s", exc) |
| 137 | +except SpanPanelGrpcError as exc: |
| 138 | + # Other gRPC-level errors |
| 139 | + logger.error("Gen3 gRPC error: %s", exc) |
| 140 | +``` |
| 141 | + |
| 142 | +Gen3 does not have built-in retry logic — reconnect handling should be implemented at the integration layer (e.g., the Home Assistant coordinator). |
0 commit comments