# Erreurs & gestion des erreurs
SUMMARY: Codes d'état HTTP, format de réponse d'erreur et comment se remettre des erreurs courantes.

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.

Erreurs & gestion des erreurs
Synapse utilise les codes d'état HTTP standard avec un format de réponse d'erreur
cohérent. Cette page explique comment interpréter et récupérer les erreurs.
Format de réponse d'erreur
Toutes les erreurs renvoient du JSON avec cette structure :
[CODE BLOCK]
| Champ | Description |
|-------|-------------|
|  | Code d'état HTTP |
|  | Nom de l'état HTTP |
|  | Description de l'erreur lisible par l'humain |
|  | URL vers la documentation pertinente (le cas échéant) |
Codes d'état HTTP
200 OK
Succès. La requête a été traitée correctement.
201 Created
Succès. Une nouvelle ressource a été créée (ex. ).
204 No Content
Succès. Aucun corps renvoyé (ex. ).
400 Bad Request
La requête était mal formée. Causes courantes :
- Champs JSON requis manquants
- Syntaxe JSON invalide
- Valeur d'énumération invalide (ex. mauvaise catégorie)
[CODE BLOCK]
Correction : Vérifiez le corps de la requête par rapport à la documentation de
l'API. Assurez-vous que tous les champs requis sont présents et ont des valeurs valides.
401 Unauthorized
L'authentification a échoué. Causes courantes :
- En-tête  manquant
- Mind Key ou JWT invalide
- Utilisation d'une Mind Key là où un JWT est requis (ou inversement)
[CODE BLOCK]
Correction : Vérifiez votre jeton. Voir Authentification.
403 Forbidden
Vous êtes authentifié mais n'êtes pas autorisé à effectuer cette action. Causes
courantes :
- Tentative de suppression du mind d'un autre utilisateur
- Tentative de vérifier une mémoire avec une Mind Key (nécessite un JWT)
- Le mind est désactivé
Correction : Vérifiez si vous utilisez le bon type de jeton pour cet endpoint.
404 Not Found
Le chemin ou la ressource demandée n'existe pas.
> [!CRITICAL]
> Ne devinez PAS les chemins d'endpoints. Seuls les chemins listés dans
>  existent. Si vous obtenez un 404, c'est que vous avez utilisé un
> mauvais chemin.
[CODE BLOCK]
Correction : Appelez  pour voir la liste des endpoints valides.
Comparez votre URL à la liste caractère par caractère.
409 Conflict
La requête entre en conflit avec l'état existant. Causes courantes :
- Tentative d'inscription avec un email déjà existant
- URL de webhook en doublon
Correction : Utilisez une valeur différente, ou utilisez  pour mettre à jour
la ressource existante.
429 Too Many Requests
Vous avez atteint une limite de débit. S'applique uniquement à l'authentification par
paramètre de requête  (60/min).
[CODE BLOCK]
En-têtes de réponse :
[CODE BLOCK]
Correction : Passez à l'en-tête  (sans limite de débit), ou
attendez  secondes.
500 Internal Server Error
Erreur serveur. Cela ne devrait pas arriver — si c'est le cas, c'est un bug.
Correction :
1. Réessayez avec un backoff exponentiel (1 s, 2 s, 4 s, 8 s)
2. Vérifiez  pour voir si le serveur fonctionne
3. Si cela persiste, signalez l'erreur
503 Service Unavailable
Le serveur est temporairement indisponible (ex. pendant un déploiement, une migration
de base de données).
Correction : Attendez et réessayez. Vérifiez .
Schémas de récupération
Réessai avec backoff exponentiel
[CODE BLOCK]
Gestion des erreurs d'authentification
[CODE BLOCK]
Scénarios d'erreur courants
"Mind Key fehlt oder ungültig"
- Vous avez oublié l'en-tête 
- Vous avez utilisé  mais la clé est erronée
- Vous utilisez un JWT là où une Mind Key est requise
"Route not found"
- Vous avez deviné un chemin qui n'existe pas
- Vous avez utilisé un verbe incorrect (ex.  vs )
- Vérifiez  pour les chemins valides
"Rate limit exceeded"
- Vous utilisez  et avez dépassé 60 req/min
- Passez à l'en-tête 
Prochaines étapes
- Authentification
- Vue d'ensemble de l'API
- Limites de débit