Erreurs

Quand une requête échoue, l'API retourne un objet d'erreur structuré avec un code HTTP adapté et un corps JSON descriptif.

Format d'erreur standard

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Le champ 'title' est obligatoire.",
    "details": [
      {
        "field": "title",
        "message": "Ce champ est requis."
      }
    ]
  },
  "meta": {
    "requestId": "req_01HXYZ123456"
  }
}

Champ	Type	Description
`error.code`	`string`	Code machine identifiant le type d'erreur.
`error.message`	`string`	Message lisible décrivant le problème.
`error.details`	`array`	Détails supplémentaires, notamment les champs invalides (optionnel).
`meta.requestId`	`string`	Identifiant unique de la requête, utile pour le support.

Codes d'erreur

Code HTTP	Code erreur	Description
`400`	`VALIDATION_ERROR`	Données de requête invalides (champ manquant, mauvais type, valeur hors plage).
`401`	`UNAUTHORIZED`	Clé API manquante ou invalide.
`403`	`FORBIDDEN`	Permission insuffisante pour effectuer cette action.
`403`	`PLAN_LIMIT_REACHED`	La limite de ton plan a été dépassée (ex: nombre d'idées).
`404`	`NOT_FOUND`	La ressource demandée est introuvable.
`409`	`CONFLICT`	Conflit avec l'état actuel (ex: tu as déjà voté pour cette idée).
`429`	`RATE_LIMITED`	Trop de requêtes. Attends avant de réessayer.
`500`	`INTERNAL_ERROR`	Erreur interne du serveur. Réessaie ultérieurement ou contacte le support.

Conseils de gestion des erreurs

Gère les 401 en priorité. Si tu reçois UNAUTHORIZED, vérifie que ta clé API est correctement transmise dans l'en-tête X-API-Key et qu'elle n'a pas été révoquée.

Distingue 403 FORBIDDEN de 403 PLAN_LIMIT_REACHED. Le premier indique une permission manquante sur ta clé — ajoute-la depuis le tableau de bord. Le second indique une limite de plan — mets à jour ton abonnement.

Implémente un backoff exponentiel pour les 429. Quand tu reçois RATE_LIMITED, attends avant de réessayer. L'en-tête Retry-After indique le nombre de secondes à attendre.

Conserve le requestId en cas d'erreur 500. Transmets-le à l'équipe support pour accélérer le diagnostic.

# Exemple : vérifier le code d'erreur dans un script shell
response=$(curl -s -o body.json -w "%{http_code}" \
  https://api.saasy.fr/api/v1/ideas \
  -H "X-API-Key: fbk_xxxxx")

if [ "$response" -ne 200 ]; then
  error_code=$(cat body.json | jq -r '.error.code')
  echo "Erreur : $error_code"
fi