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 :

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

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)

{
  "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)

{
  "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.

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.

{
  "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).

{
  "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

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

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
• Vue d'ensemble de l'API
• Limites de débit