Erreurs API

L'API signale les erreurs avec des codes de statut HTTP standard et un corps de réponse unifié. Les réponses réussies renvoient les données directement, sans enveloppe.

Format d'erreur

En cas d'erreur, le corps de la réponse est un objet JSON avec un seul champ error contenant un message lisible par un humain :

{"error":"reaction not found"}

Basez-vous en priorité sur le code de statut HTTP, et utilisez le texte error pour les logs et les messages à l'utilisateur.

Codes de statut

  • 200 OK — requête réussie, données dans le corps.
  • 201 Created — nouvelle ressource créée (certains endpoints POST).
  • 204 No Content — succès sans corps (certaines suppressions).
  • 400 Bad Request — corps ou paramètres de requête incorrects.
  • 401 Unauthorized — jeton absent, invalide ou expiré ; ou route inaccessible avec un jeton personnel.
  • 402 Payment Required — l'action est limitée par un forfait ou un quota (par exemple, le stockage de médias propre nécessite un abonnement premium).
  • 403 Forbidden — le jeton ne dispose pas de la portée nécessaire pour cette route.
  • 404 Not Found — ressource introuvable ou ne vous appartenant pas.
  • 409 Conflict — conflit d'état (par exemple, doublon d'une valeur unique).
  • 422 Unprocessable Entity — le corps est syntaxiquement valide mais ne passe pas les validations métier.
  • 429 Too Many Requests — limite de requêtes dépassée (voir limites).
  • 500 Internal Server Error — erreur interne du serveur ; réessayez plus tard.

Comment gérer les erreurs

Considérez les codes 2xx comme des succès. Pour 401/403, vérifiez le jeton et ses portées. Pour 4xx (sauf 429), ne répétez pas la requête sans modification — corrigez-la d'abord. Pour 429 et 5xx, un retry avec délai exponentiel est approprié.

Pour aller plus loin