# Errori e limiti di frequenza
Source: https://nordvec.com/it/docs/guides/errors-and-rate-limits

La singola busta di errore che ogni richiesta fallita restituisce, le intestazioni del limite di frequenza e come ritentare una scrittura in modo sicuro.



Ogni endpoint fallisce allo stesso modo, quindi un client gestisce errori, limiti di frequenza e tentativi una volta sola e riutilizza quel codice ovunque, incluso su [MCP](/docs/guides/mcp).

## La busta di errore [#la-busta-di-errore]

Ogni risposta non-2xx è un oggetto JSON:

```json
{
  "defined": false,
  "code": "TOO_MANY_REQUESTS",
  "message": "Too many requests",
  "data": { "reason": "rate_limit.exceeded", "retryAfterMs": 12000 }
}
```

* `code` è l'errore a livello HTTP, ad esempio `UNAUTHORIZED`, `FORBIDDEN`,
  `NOT_FOUND`, `BAD_REQUEST` o `TOO_MANY_REQUESTS`.
* `data.reason`, quando presente, è un motivo più preciso leggibile dalla macchina come
  `auth.key_not_found` o `rate_limit.exceeded`. Fai branching su questo piuttosto che su
  `message`, che è per le persone e può cambiare.
* `defined` è `true` quando l'operazione elenca quell'errore nella
  [riferimento API](/docs/api), e `false` per errori che qualsiasi richiesta può incontrare
  (autenticazione, limiti di frequenza, una rotta sconosciuta).
* Un fallimento di validazione risponde `BAD_REQUEST` con i problemi in
  `data.formErrors` e `data.fieldErrors`.

Ogni risposta include anche un `X-Request-ID`. Citalo quando contatti
l'assistenza, così possiamo trovare quella richiesta esatta.

## Stati comuni [#stati-comuni]

| Stato | Codice                  | Cosa fare                                                                          |
| ----- | ----------------------- | ---------------------------------------------------------------------------------- |
| `400` | `BAD_REQUEST`           | Correggi la richiesta; `data.fieldErrors` indica i campi                           |
| `401` | `UNAUTHORIZED`          | Invia una chiave o sessione valida                                                 |
| `403` | `FORBIDDEN`             | La chiave non ha lo scope o il ruolo richiesto dall'operazione                     |
| `404` | `NOT_FOUND`             | La risorsa non esiste, oppure non hai il permesso di vederla                       |
| `409` | `CONFLICT`              | Una scrittura duplicata è ancora in corso; riprova tra poco                        |
| `413` | `PAYLOAD_TOO_LARGE`     | Il corpo della richiesta supera 1 MB; suddividi un invio bulk in batch più piccoli |
| `422` | `UNPROCESSABLE_CONTENT` | La richiesta è ben formata ma non può essere applicata                             |
| `429` | `TOO_MANY_REQUESTS`     | Attendi `Retry-After`, poi riprova                                                 |

## Limiti di frequenza [#limiti-di-frequenza]

Ogni risposta indica il limite contro cui è stata conteggiata, in due forme:

* le intestazioni `X-RateLimit-*`;
* i campi strutturati IETF `RateLimit` (stato attuale: `r` sono le richieste
  rimanenti, `t` i secondi fino al reset della finestra) e `RateLimit-Policy`
  (la quota: `q` è il limite, `w` la finestra in secondi).

Una `429` include anche `Retry-After` in secondi e `data.retryAfterMs`. Attendi almeno quel tempo
prima della prossima richiesta; riprovare prima viene conteggiato e rifiutato di nuovo.

## Ripetizione sicura delle scritture [#ripetizione-sicura-delle-scritture]

Un'operazione di scrittura che elenca un'intestazione `Idempotency-Key` nella
[riferimento API](/docs/api) può essere ripetuta senza eseguire il lavoro due volte. Invia
una chiave per ogni scrittura logica e ripeti la stessa chiave in ogni tentativo:

* la stessa chiave con lo stesso corpo entro 24 ore riproduce la risposta memorizzata;
* la stessa chiave con un corpo diverso viene rifiutata con `422`;
* un duplicato che arriva mentre il primo è ancora in esecuzione riceve `409`.

Un'operazione senza l'intestazione non è idempotente, quindi ripetila solo quando sai che il primo tentativo non è andato a buon fine.