Retry transient server errors on setup (fixes #392)

[rhammen]

Fixes #392. Closes #360.

Part A (retrying transient 5xx for the token request) is exactly what #360 ("Retry token on 503 responses") asked for, so this PR resolves both.

Built on top of #391 (Add offline unit tests for the Zaptec API client) — the tests here reuse its FakeSession / _make_zaptec harness.

The bug

On a fresh install (e.g. a dev-container), adding a Zaptec account intermittently fails setup with a 503 from the token endpoint, and only a full Home Assistant restart recovers:

RequestError: POST request to https://api.zaptec.com/oauth/token failed with status 503
ConfigEntryError: ... 503 Service Temporarily Unavailable

Reported by @sveinse in #392, who correctly suspected a race: setup issues a second /oauth/token POST within ~200 ms of the first, and the server occasionally answers that one with a transient 503.

Root cause

1. No retry on transient 5xx for the token request. _refresh_token branched only on 200 (return) and 400 (auth error); every other status — including 503 — fell straight through to raise RequestError(...) on the first response. The retry loop in _request_worker only re-looped on TimeoutError / ClientConnectionError, never on an HTTP status.
2. A transient error mapped to a permanent setup failure. In async_setup_entry, a RequestError (subclass of ZaptecApiError) became ConfigEntryError, which HA treats as permanent (no auto-retry). Only timeout/connection errors mapped to ConfigEntryNotReady. That's why only a restart recovered.

The fix

A — Retry transient statuses in _request_worker (zaptec/api.py, zaptec/const.py)

• New RETRYABLE_HTTP_STATUSES = frozenset({HTTPStatus.TOO_MANY_REQUESTS, HTTPStatus.BAD_GATEWAY, HTTPStatus.SERVICE_UNAVAILABLE, HTTPStatus.GATEWAY_TIMEOUT}).
• The worker now retries those statuses for all methods using the existing exponential backoff, honoring a Retry-After header when present (as a floor on top of the computed backoff, never shortening it). On the final attempt it still yields the response so the caller raises its normal RequestError(status). This fixes the token POST and every request() call from one place.
• Deliberately not including 500: Zaptec returns 500 in various application-level cases, so it keeps its current behavior (retried only for GET). 429/502/503/504 are infrastructure-level "try again shortly" errors where the request typically never reached the app, so retrying is safe even for POST/PUT — no risk of double-executing a non-idempotent command.

B — Map transient errors to ConfigEntryNotReady (__init__.py)

• Extracted _config_entry_error(), which maps auth failures → ConfigEntryAuthFailed, and connection/timeout errors and transient 429/502/503/504 → ConfigEntryNotReady (HA auto-retries setup). All other API errors remain permanent ConfigEntryError.

Testing

Offline unit tests (built on #391's harness, no network/credentials needed):

• Per-status retry-then-success for 429/502/503/504, plus a transient 503 retried on a POST.
• Persistent 503 retried to exhaustion → RequestError with error_code == 503 (for both request() and the token endpoint).
• Retry-After header honored as a floor on the backoff delay.
• _config_entry_error() mapping table (auth / timeout / connection / 503 / 429 / 403 / 404).

Existing regression tests (500-on-POST not retried, 500-on-GET retried) continue to pass, confirming the 500 path is unchanged. Full offline suite green locally (SKIP_ZAPTEC_API_TEST=true), ruff format/ruff check clean.

🤖 Generated with Claude Code

[sveinse]

Please sync this project with the latest version version in master.

[sveinse]

Some tips:

It is useful (and necessary) to get information that the PR is stacked and builds on previous PRs. But there is no need to explain in the description on how to merge the staged PRs. Please keep the description to the point what they fix.

All PRs must apply cleanly and only contain the relevant changes before merge. We use squash merge, and all previous PRs which this builds on will not share any history. Thus, master must be merged into the PR branch right before its ready to be merged into master (this happens after all its dependent PRs have been merged). When the final merge has been done, the diff is clean and will only contain the diff. No commits from the PR branch will be preserved.

[rhammen]

Pushed an update addressing the review feedback:

• RETRYABLE_HTTP_STATUSES now uses HTTPStatus enum members instead of raw integers.
• Retry-After can now only extend the computed backoff delay, never shorten it (sleep_delay = max(sleep_delay, retry_after)), to avoid a short Retry-After resetting our own backoff progression.
• Merged master into the branch now that Add offline unit tests for the Zaptec API client #391 is in, so the diff no longer carries its commits (also picks up Fix ruff lint errors in api.py #390 and Use requirements.txt for ruff version in ci-pipeline #407).

Also trimmed the PR description down to just what this fixes, per the note above.

Still open: the docs/superpowers/specs/... design-doc question — happy to hear more input on whether to keep this pattern going forward.

[sveinse]

Awesome. I'm happy with this PR given that we remove the docs/superpowers/ document.

Since many PRs are staggered on each other, it doesn't make sense to review the other PRs just yet. We'll have to do them one by one which will take some time with some back and forth.

[sveinse]

This look good. Thank you @rhammen

[sveinse]

@rhammen could you be so kind to help with one thing please: The squash commit message will be extremely long with overwhelming amount of text from all the commits. Can you propose (use Claude if you prefer) to make a short, to-the-point, single commit message that sums up everything in this PR, please? It should contain what the intent of the PR is in short concise language, not a verbose list of all that's changed (it is possible to read the diff). Please post the proposal as a comment.

[rhammen]

Proposed squash-merge commit message:

Retry transient server errors instead of failing setup permanently (#392)

Transient errors from the Zaptec API (429/502/503/504, or connection/
timeout errors) previously caused Home Assistant to treat the
integration as permanently failed during setup, requiring manual
intervention. Add backoff-based retries for these infrastructure-level
errors, and map any that still occur during setup to
ConfigEntryNotReady so Home Assistant retries automatically instead.

Fixes #392.