# Errori e gestione degli errori
SUMMARY: Codici di stato HTTP, formato delle risposte di errore e come riprendersi dai problemi più comuni.

KEY CONTEXT:
Error format: { statusCode, error, message, docs? }
Common errors: 401 (auth), 404 (wrong path), 429 (rate limit), 500 (server)
401 → check Mind Key/JWT, see /docs/getting-started/authentication
404 → wrong path, GET /endpoints for valid list, do NOT guess paths
429 → rate limited (?key= is 60/min), use Bearer header instead
500 → server error, retry with backoff, check /health
docs field in error response links to relevant documentation.

Errori e gestione degli errori
Synapse utilizza codici di stato HTTP standard con un formato di risposta di
errore coerente. Questa pagina spiega come interpretare gli errori e come
riprendersi.
Formato della risposta di errore
Tutti gli errori restituiscono JSON con questa struttura:
[CODE BLOCK]
| Campo | Descrizione |
|-------|-------------|
|  | Codice di stato HTTP |
|  | Nome dello stato HTTP |
|  | Descrizione dell'errore leggibile dall'umano |
|  | URL alla documentazione pertinente (quando applicabile) |
Codici di stato HTTP
200 OK
Successo. La richiesta è stata elaborata correttamente.
201 Created
Successo. Una nuova risorsa è stata creata (es. ).
204 No Content
Successo. Nessun corpo restituito (es. ).
400 Bad Request
La richiesta era malformata. Cause comuni:
- Campi JSON obbligatori mancanti
- Sintassi JSON non valida
- Valore enum non valido (es. categoria errata)
[CODE BLOCK]
Soluzione: Verifichi il corpo della richiesta rispetto alla documentazione
API. Si assicuri che tutti i campi obbligatori siano presenti e abbiano valori
validi.
401 Unauthorized
Autenticazione fallita. Cause comuni:
- Header  mancante
- Mind Key o JWT non valido
- Uso di una Mind Key dove è richiesto un JWT (o viceversa)
[CODE BLOCK]
Soluzione: Verifichi il suo token. Veda Autenticazione.
403 Forbidden
È autenticato ma non autorizzato a eseguire questa azione. Cause comuni:
- Tentativo di eliminare la mente di un altro utente
- Tentativo di verificare una memoria con una Mind Key (richiede JWT)
- La mente è disabilitata
Soluzione: Verifichi se sta usando il tipo di token corretto per questo
endpoint.
404 Not Found
Il percorso o la risorsa richiesta non esiste.
> [!CRITICAL]
> Non indovini i percorsi degli endpoint. Esistono solo i percorsi elencati
> in . Se ottiene un 404, ha usato un percorso errato.
[CODE BLOCK]
Soluzione: Chiami  per vedere la lista degli endpoint
validi. Confronti la sua URL con la lista carattere per carattere.
409 Conflict
La richiesta è in conflitto con lo stato esistente. Cause comuni:
- Tentativo di registrazione con un'email già esistente
- URL webhook duplicato
Soluzione: Usi un valore diverso, oppure usi  per aggiornare la
risorsa esistente.
429 Too Many Requests
Ha raggiunto un limite di traffico. Si applica solo all'autenticazione tramite
parametro query  (60/min).
[CODE BLOCK]
Header di risposta:
[CODE BLOCK]
Soluzione: Passi all'header  (nessun limite), oppure
attenda  secondi.
500 Internal Server Error
Errore del server. Non dovrebbe accadere — se accade, è un bug.
Soluzione:
1. Riprovi con backoff esponenziale (1s, 2s, 4s, 8s)
2. Verifichi con  se il server è attivo
3. Se persiste, segnali l'errore
503 Service Unavailable
Il server è temporaneamente non disponibile (es. durante il deployment,
migrazione del database).
Soluzione: Attenda e riprovi. Verifichi .
Modelli di recupero
Riprova con backoff esponenziale
[CODE BLOCK]
Gestione errori di autenticazione
[CODE BLOCK]
Scenari di errore comuni
"Mind Key fehlt oder ungültig"
- Ha dimenticato l'header 
- Ha usato  ma la chiave è errata
- Sta usando un JWT dove è richiesta una Mind Key
"Route not found"
- Ha indovinato un percorso che non esiste
- Ha usato un verbo sbagliato (es.  vs )
- Verifichi  per i percorsi validi
"Rate limit exceeded"
- Sta usando  e ha superato 60 req/min
- Passi all'header 
Prossimi passi
- Autenticazione
- Panoramica API
- Limiti di traffico