# Statuskoder & felsvar

Skillnaden mellan "förnya token", "logga in på nytt" och "sluta försöka" är det som avgör om integrationen återhämtar sig eller låser ute kontot.

```json
{
  "status": 401,
  "title": "Unauthorized",
  "detail": "The access token has expired."
}
```

Behandla `status` som sanningen. Textfälten är avsedda för loggar och felsökning, inte för att matchas på i kod.

## Katalog

| Status | Var | Vad som hänt | Klientens åtgärd |
| --- | --- | --- | --- |
| `400` | `/auth/refresh` | Refresh-token saknas, är förbrukad eller felformad | **Full ominloggning.** Retry:a aldrig samma token |
| `400` | `/auth/login-by-phone` | `phoneNumber` matchar inte `^[+][0-9]{9,13}$`, eller fält saknas | Rätta begäran. Ingen retry |
| `401` | Alla skyddade anrop | Access-token saknas, är utgången eller ogiltig | **Förnya en gång**, gör om anropet en gång |
| `401` | `/auth/refresh` | Refresh-token förbrukad eller utgången | **Full ominloggning.** Aldrig retry på token |
| `401` | Direkt efter lyckad förnyelse | Sessionen övertagen av en annan inloggning | **Sluta.** Larma. Loopa inte |
| `403` | `/device/{deviceId}/*` | Kontot har ingen nyckel till enheten | **Sluta.** Kontakta KiiOn om nyckeldelning |
| `404` | `/device/{deviceId}/*` | Okänt `{deviceId}`, eller enheten tillhör inte kontot | Hämta enhetslistan på nytt och uppdatera mappningen |
| `409` | Auth | Sessionen ersattes av en samtidig inloggning | **Sluta.** Säkerställ en singleton per konto |
| `429` | Alla | För många anrop | Respektera `Retry-After`. Exponentiell backoff med jitter |
| `500` | Alla | Fel på serversidan | Backoff, försök igen — utom på unlock |
| `502` / `503` / `504` | `/device/{deviceId}/unlock` | Enheten eller gatewayen svarar inte | **Retry:a inte automatiskt.** Visa felet för användaren |

## Tre regler som räcker

1. **`401` på ett vanligt anrop** = förnya och gör om en gång. Fortsätter det: sluta.
2. **`401`/`400` från `/auth/refresh`** = token är död. Logga in på nytt, aldrig retry.
3. **`403` och `404`** går inte att försöka sig ur. `403` kräver en nyckel, `404` kräver en ny mappning.

> **Unlock är inte idempotent i praktiken** — Ett upprepat `PUT /device/{deviceId}/unlock` kan öppna dörren en gång till. Behandla den aldrig som säker att retry:a automatiskt — se [Gränser & retry](/docs/limits#unlock-retry).

**Vidare**
- [Beslutstabellen för tokenfel](/docs/authentication#failure-handling)
- [Felsökning & FAQ — symtom och orsak](/docs/troubleshooting)
- [/openapi.json — samma kontrakt, maskinläsbart](/openapi.json)