---
title: "Erreurs JSON"
description: "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."
canonical: https://developer.billabex.com/fr/guides/erreurs/
lang: fr
alternate: https://developer.billabex.com/en/guides/errors/
last-updated: 2026-10-01
---

# 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.

Source: https://developer.billabex.com/fr/guides/erreurs/
Langue: Français (fr)
Version anglaise: https://developer.billabex.com/en/guides/errors/

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.

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

## Deux origines, une règle : jamais d'erreur en HTML

L'API et ce site de documentation sont deux origines distinctes, et aucune des deux ne répond à une machine par une page HTML.

- **L'API** (`https://next.billabex.com`) répond en JSON sur tous ses chemins, erreurs comprises, dans la forme ci-dessus.
- **Le portail développeur** (`developer.billabex.com`) sert des documents, pas du JSON. Une requête qui y préfère `application/json` est refusée par un `406 Not Acceptable` accompagné d'un corps JSON portant `code`, `message`, `resolution` et la liste des types réellement disponibles. Une requête sous `/api/` est redirigée vers l'API par un `308`, qui conserve la méthode et le corps : un client qui confond l'hôte de documentation avec l'API atterrit quand même sur une réponse JSON.

```json
{
  "code": "DOCUMENTATION_NOT_AVAILABLE_AS_JSON",
  "message": "The Billabex developer portal serves documentation as text/html and text/markdown. It has no JSON representation of this path.",
  "resolution": "Request text/html or text/markdown for documentation, read the OpenAPI specification at /openapi.json, or call the Billabex public API, whose every response is JSON.",
  "path": "/fr/guides/erreurs/",
  "method": "GET",
  "type": "http",
  "available": ["text/html", "text/markdown"]
}
```

## Validation des dates

| Code                                       | Correction                                                      |
| ------------------------------------------ | --------------------------------------------------------------- |
| `app-invoicing.date.due-before-issued`     | Choisir une échéance égale ou postérieure à la date d’émission. |
| `app-invoicing.date.issued-in-future`      | Choisir une date d’émission au plus tard aujourd’hui.           |
| `app-dunning.email.scheduled-date-invalid` | Fournir une date et une heure d’envoi valides.                  |
| `app-dunning.email.scheduled-date-in-past` | Choisir une date et une heure d’envoi à venir.                  |

---

Billabex developer portal. OpenAPI specification: https://developer.billabex.com/openapi.json.
Agent instructions: https://developer.billabex.com/llms.txt. Complete documentation: https://developer.billabex.com/llms-full.txt.