# Errori e limiti di frequenza

Gli errori dell’API di KolWrite sono risposte JSON con un `code` stabile ogni volta che
il client può intervenire.

```json
{
  "detail": {
    "code": "insufficient_scope",
    "message": "This endpoint requires the 'jobs:write' scope",
    "required_scope": "jobs:write"
  }
}
```

## Stati comuni

| Stato | Significato |
|---|---|
| `400` | Input non valido o combinazione di opzioni non supportata |
| `401` | Token mancante, non valido, scaduto o revocato |
| `403` | Il token è valido ma mancano l’ambito o l’accesso alla route |
| `404` | La risorsa non esiste o non è visibile al proprietario del token |
| `409` | Conflitto, di solito di idempotenza o di cambio di stato |
| `422` | Il corpo della richiesta è JSON valido ma non supera la validazione |
| `429` | Limite di frequenza o pressione sulla riserva di crediti |
| `5xx` | Errore temporaneo del servizio KolWrite |

## Indicazioni sui nuovi tentativi

Riprova dopo `429`, `502`, `503` e `504` con backoff esponenziale e jitter.
Usa `Idempotency-Key` alla creazione dei job perché i nuovi tentativi dovuti alla rete non creino mai
job duplicati. Non riprovare dopo `401`, `403` o errori di validazione finché
non correggi il token o la richiesta.