# DDR-0020: E27 api_link Provisioning Failure is Silent; Timeout is the Only Signal

Status: Approved
Date: 2025-12-22
Applies to: elkm1/elke27_lib linking/provisioning flow (api_link)
Related ADRs: ADR-0006 (E27 Transport and Link Layer Separation)
Related DDRs: DDR-0019 (Provisioning vs Runtime Responsibilities and Module Boundaries)

## Context

The E27 `api_link` exchange is a provisioning-time operation that associates an
application instance with a panel and yields link credentials (linkkey/linkhmac).

During live testing, it was verified that when provisioning credentials are
incorrect (access code and/or passphrase), the panel does not send any error
response and does not respond at all to the `api_link` request.

Therefore, the client cannot reliably distinguish:
- invalid access code
- invalid passphrase
- incorrect identity fields (mn/sn/version inputs)
- transient transport issues
based on protocol response content, because no response is produced.

## Decision

For `api_link` provisioning, lack of response within a defined timeout MUST be
treated as the canonical failure signal.

Implementation requirements:

- `linking.py` / provisioning logic MUST implement a bounded wait for the
  `api_link` response.
- If no response is received before timeout expiration, provisioning MUST fail
  with a structured error that indicates a timeout/no-response condition.
- The library MUST NOT claim “invalid access code” or “invalid passphrase” as a
  fact, since the protocol does not provide that certainty.
- Home Assistant (or any caller) MUST present user-facing messaging that reflects
  this ambiguity (e.g., “panel did not respond; verify access code/passphrase and
  connectivity”), and should initiate an interactive retry if desired.

## Consequences

- Provisioning error handling is timeout-centric rather than response-code-centric.
- Retry policy is a caller concern (e.g., Home Assistant config flow), not a
  library concern, to avoid unbounded delays or unintended lockout behavior.
- Test tooling must validate both success and silent-failure (timeout) behavior.

## Notes

This DDR applies only to the `api_link` provisioning step. Other protocol phases
(e.g., authenticated API calls) may return explicit error_code fields and should
be handled using normal structured response parsing.
