#Codes d’erreur

Un intégrateur passe l’essentiel de son temps sur les 4xx. Cette page liste tous les codes que l’API émet, ce qui les a déclenchés, et la conduite à tenir — puis explique la seule limite de débit du produit, ce qu’elle arrête et ce qu’elle n’arrête pas.

#La forme d’une réponse d’erreur

{
  "error": "fichier_requis",
  "message": "Ce fichier est indispensable au thème : il ne peut pas être supprimé."
}

error est un code stable, en minuscules avec des tirets bas. C’est lui qu’on compare en code, et lui seul : il ne changera pas de nom sans que le journal le dise.

message est une phrase rédigée en français, destinée à être affichée telle quelle. Elle n’apparaît que là où le code seul ne suffirait pas à savoir quoi faire. Ne la comparez jamais — elle peut être reformulée sans préavis.

Un seul refus porte un troisième champ : site_inactif ajoute etat. Aucun autre code n’en emporte.

#Authentification et accès

#Facturation

402 Payment Required et non 403, parce que « tu n’as pas le droit » et « ta formule ne le couvre pas » appellent deux interfaces très différentes — un message d’erreur d’un côté, une proposition de changer de formule de l’autre — et un client ne peut pas les distinguer si le serveur répond la même chose.

Le champ etat accompagne le refus et vaut essai, actif, retard, expire ou aucun. Il est informatif : c’est site_inactif qui décide, pas lui.

Les lectures restent ouvertes. DELETE /api/themes aussi — retirer un brouillon ne change rien à ce que voient les visiteurs, et un site en fin d’essai peut encore faire le ménage chez lui.

#Requête et ressource

#Format d’un fichier ou d’une archive

Ces codes viennent de la validation du format des thèmes. Ils sont identiques que l’on écrive un fichier, qu’on duplique un thème ou qu’on importe une archive.

#Pannes serveur

Les deux derniers sortent en 400 et non en 500 : ils remontent de la validation d’installation, qui rend un seul statut pour toutes ses raisons. C’est un écart assumé, à connaître si tu branches une alerte sur les 5xx — ces deux-là ne s’y verront pas.

#La limitation de débit

Un seul compteur dans toute l’API, et il ne porte pas sur les requêtes réussies.

{ "error": "trop_de_tentatives" }

#Ce que ce compteur arrête, et ce qu’il n’arrête pas

Il n’arrête pas une recherche exhaustive de secret. 256 bits ne se devinent pas, et de toute façon chaque essai aurait une empreinte différente, donc son propre compteur. Prétendre le contraire serait se raconter une histoire.

Ce qu’il arrête, c’est le cas réel et fréquent : une clé révoquée ou périmée qu’un CI continue de présenter en boucle, plusieurs fois par minute, indéfiniment. Sans compteur, chaque tentative coûte un aller-retour de base — et un CI mal réglé fait plus de dégâts qu’un attaquant.

Un refus déjà prononcé est mémorisé une minute dans le processus qui l’a rendu : la onzième tentative et les suivantes repartent sans le moindre accès à la base. C’est ce que le compteur promettait et ne tenait pas au départ — il était consulté après la vérification, donc il ne pouvait rien économiser.

#Que faire selon le code

1. 401, 403, 429 : arrêter la boucle

   Ces trois-là ne se réparent pas en réessayant. Un script qui relance un pousser après un 401 transforme une clé périmée en dix tentatives, puis en 429. Le CLI s’arrête ; faites de même.

2. 402 : c’est de la facturation, pas de la technique

   Aucun en-tête, aucune option, aucun autre mode d’authentification ne contourne site_inactif. Le contournement a existé — une clé écrivait là où le navigateur était refusé — et il a été fermé.

3. 400 : lire `error`, pas `message`

   Six causes derrière un même statut. syntaxe demande de corriger un fichier, trop_de_fichiers d’en supprimer un, invalid_input de relire le schéma de la route. Voir Fichiers et Thèmes.

4. 404 : distinguer le thème du fichier

   introuvable veut dire que l’uuid ou le site est faux. fichier_introuvable veut dire que le thème est bon et que le chemin ne l’est pas.

5. 5xx : réessayer une fois, puis signaler

   Rien n’est perdu à rejouer. Si le refus persiste, ce n’est pas la requête qui est en cause.