# 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 :

```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Mind Key fehlt oder ungültig.",
  "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"
}
```

| Champ | Description |
|-------|-------------|
| `statusCode` | Code d'état HTTP |
| `error` | Nom de l'état HTTP |
| `message` | Description de l'erreur lisible par l'humain |
| `docs` | 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. `POST /memory`).

### 204 No Content

Succès. Aucun corps renvoyé (ex. `DELETE /memory/:id`).

### 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)

```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "category must be one of: identity, preference, fact, project, skill, mistake, context, note, credentials"
}
```

**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 `Authorization` manquant
- Mind Key ou JWT invalide
- Utilisation d'une Mind Key là où un JWT est requis (ou inversement)

```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Mind Key fehlt oder ungültig.",
  "docs": "https://synapse.schaefer.zone/docs/getting-started/authentication"
}
```

**Correction :** Vérifiez votre jeton. Voir [Authentification](/docs/getting-started/authentication).

### 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
> `GET /endpoints` existent. Si vous obtenez un 404, c'est que vous avez utilisé un
> mauvais chemin.

```json
{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Route GET /memory/list not found",
  "docs": "https://synapse.schaefer.zone/docs/api/errors"
}
```

**Correction :** Appelez `GET /endpoints` 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 `PUT` 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 `?key=` (60/min).

```json
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Use Authorization header for unlimited access."
}
```

En-têtes de réponse :

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 42
```

**Correction :** Passez à l'en-tête `Authorization: Bearer` (sans limite de débit), ou
attendez `Retry-After` 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 `GET /health` 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 `GET /health`.

## Schémas de récupération

### Réessai avec backoff exponentiel

```python
import time
import requests

def call_with_retry(url, max_retries=3):
    for attempt in range(max_retries):
        try:
            r = requests.get(url, headers={"Authorization": f"Bearer {KEY}"})
            if r.status_code == 429:
                wait = int(r.headers.get("Retry-After", 60))
                time.sleep(wait)
                continue
            if r.status_code >= 500:
                time.sleep(2 ** attempt)
                continue
            return r
        except requests.RequestException:
            time.sleep(2 ** attempt)
    raise Exception(f"Failed after {max_retries} retries")
```

### Gestion des erreurs d'authentification

```python
def safe_call(url, key):
    r = requests.get(url, headers={"Authorization": f"Bearer {key}"})
    if r.status_code == 401:
        # Mind Key invalide — avertir l'utilisateur
        raise AuthError("Mind Key invalid or expired")
    return r
```

## Scénarios d'erreur courants

### "Mind Key fehlt oder ungültig"

- Vous avez oublié l'en-tête `Authorization`
- Vous avez utilisé `?key=` 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. `GET /memory` vs `POST /memory`)
- Vérifiez `GET /endpoints` pour les chemins valides

### "Rate limit exceeded"

- Vous utilisez `?key=` et avez dépassé 60 req/min
- Passez à l'en-tête `Authorization: Bearer`

## Prochaines étapes

- [Authentification](/docs/getting-started/authentication)
- [Vue d'ensemble de l'API](/docs/api/overview)
- [Limites de débit](/docs/api/rate-limits)