How to recover from connection and device failures
First identify the failure boundary: documentation retrieval, registration, user authorization, token validation, scope, resource policy, payload, provider link or device observation.
| Symptom | Next step |
|---|---|
| Guide returns a login page/app shell | Use the raw Markdown link from the guide index; report the broken link to support |
| DCR invalid metadata | Correct callback, auth method, supported grants/scopes; do not invent a secret |
| Callback state/issuer mismatch | Stop; discard the response and restart authorization securely |
| Token expired | Refresh with the same client/resource or ask for renewed user consent |
insufficient_scope (403) | Do not retry. The response names the missing scope; ask the user to reconnect or approve it (see "Scopes for setup" in first-setup) |
| Policy denied | Read authorization rules; user/owner must approve access |
| Empty inventory | Valid connection can have no devices; check linking/sharing without guessing IDs |
| Invalid payload | Retrieve the exact capability version/schema and correct the request |
| Provider credential expired | Ask the user to relink the provider account |
| Stale/unavailable state | STALE is the last known state: report it with its timestamp. Errored or missing is unknown. Do not claim physical completion |
| Lost command response | Recover existing receipt/readback; retry only under documented replay guarantees |
| Committed cleanup pending | Read the committed state/result before any retry |
See API behavior. Never include tokens, provider secrets or another user's private resources in diagnostics.