Bonnes pratiques4 min

Erreurs JSON

Interpréter les erreurs de l'API Billabex par leur code, suivre la piste de résolution, et ne réessayer que lorsque la réponse l'autorise.

Les erreurs de l’API Billabex sont en JSON. Ne branchez pas sur une page HTML ni sur un message traduit destiné à un humain. Lisez le statut HTTP et le code, qui est stable, puis servez-vous de details, de resolution et des en-têtes de réponse pour décider de la suite.

{
  "message": "Invalid or missing OAuth token",
  "code": "HTTP_401",
  "frontMessage": "Authentication required",
  "timestamp": "2026-08-24T18:09:55.818Z",
  "path": "/api/public/v1/organizations",
  "type": "http",
  "method": "GET",
  "resolution": "Obtain a valid OAuth access token and retry."
}

Champs

Champ Signification
message Explication technique, pour les journaux et les développeurs.
code Code stable, lisible par une machine. Les erreurs HTTP utilisent HTTP_<statut> ; les erreurs métier leur code domaine ou applicatif.
frontMessage Message localisé facultatif, pour une interface. Ne l’utilisez pas pour piloter votre logique.
details Valeurs structurées facultatives attachées à une erreur métier, par exemple le coût en crédits calculé et le maximum autorisé.
timestamp Heure UTC à laquelle l’API a produit l’erreur.
path et method Cible de la requête qui a échoué.
type Origine de l’erreur : http, app, domain, infra ou unknown.
resolution Action suivante sûre pour un client automatisé.

Règles de reprise

  • Sur 400, corrigez la requête avant de réessayer. Un champ d’entrée inconnu est rejeté, pas ignoré.
  • Sur 401, obtenez un jeton d’accès valide par OAuth et réessayez une fois.
  • Sur 403, demandez l’un des scopes déclarés par l’opération OpenAPI, puis faites réautoriser le client.
  • Sur 404, vérifiez l’endpoint et l’identifiant de la ressource. Rejouer la même requête n’y changera rien.
  • Sur 429, attendez la durée annoncée par l’en-tête Retry-After et surveillez les en-têtes RateLimit.
  • Sur 5xx, réessayez un nombre borné de fois, avec un délai croissant. Contactez le support Billabex si l’erreur persiste.

La spécification OpenAPI rattache les réponses d’erreur à ce même schéma typé : un client généré ou un outil de function calling peut donc lire ces champs sans avoir à extraire quoi que ce soit de la documentation.