Erreurs
Toutes les erreurs de /api/v1 sont en JSON, quel que soit votre en-tête Accept, et utilisent une seule enveloppe :
{
"success": false,
"error_code": "validation_failed",
"error": "The customer id field is required. (and 4 more errors)",
"message": "The customer id field is required. (and 4 more errors)",
"errors": {
"customer_id": ["The customer id field is required."],
"issue_date": ["The issue date field is required."],
"due_date": ["The due date field is required."],
"currency": ["The currency field is required."],
"items": ["The items field is required."]
}
}
| Champ | Signification |
|---|---|
success |
Toujours false en cas d'erreur. |
error_code |
Le champ sur lequel faire correspondre. Code stable et lisible par machine : validation_failed, business_rule_violation, unauthenticated, forbidden, not_found, server_error, ou le code propre à un endpoint, tel que quote_locked, delivery_failed, payment_link_not_found. Il ne change jamais selon la langue. |
error |
Texte d'affichage, la même phrase que message. Ne vous en servez pas pour la correspondance : il est dans la langue de la requête, et une version ultérieure de l'API pourra le supprimer. Quelques anciens endpoints y placent encore leur code ; il figure aussi dans error_code. |
message |
Raison lisible, pouvant être affichée telle quelle, dans la langue de la requête (voir ci-dessous). |
errors |
Nom de champ → liste de messages. Toujours un objet — {} quand l'erreur ne concerne pas un champ précis. |
Certaines réponses ajoutent des clés à l'enveloppe (retry_after sur 429, quota et actions sur 402, error_codes par destinataire lors d'un échec de transmission d'une note de crédit). Ignorez les clés que vous ne reconnaissez pas.
Langue
Les messages suivent l'en-tête Accept-Language de la requête : sa première langue prise en charge, selon les poids propres à l'en-tête (fr-BE,fr;q=0.9 → français). Langues prises en charge : en, fr, nl, de, es, it, pt. Sans langue prise en charge, les messages sont en anglais. error_code est identique dans toutes les langues.
Échecs imprévus
Un échec qui n'est pas un refus rédigé à votre intention (un 5xx, ou un refus que le serveur n'avait pas prévu) porte un message générique accompagné d'une référence de support, par exemple …indiquant la référence 7KQ2M9XA. Indiquez-la au support : les détails sont journalisés sous cette référence. Le message ne contient jamais de détail interne.
Codes de statut
| Statut | Quand |
|---|---|
400 |
Contexte d'organisation manquant, ou requête que le point d'accès ne peut pas traiter |
401 |
Jeton absent, invalide, révoqué ou expiré |
402 |
Quota du forfait atteint — quota indique quelle limite |
403 |
Permission ou portée du jeton insuffisante ; écriture sur une organisation archivée |
404 |
Ressource ou route introuvable — ou inaccessible depuis votre organisation |
413 |
Le fichier envoyé dépasse votre quota de stockage |
422 |
Échec de validation, ou requête refusée par une règle métier (voir ci-dessous) |
429 |
Limite de débit dépassée — respectez Retry-After |
5xx |
Erreur serveur. Le message ne contient jamais de détail interne ; réessayez avec un délai croissant. |
Les points d'accès OAuth (/oauth/*) ne font pas partie de /api/v1 et suivent le format d'erreur OAuth 2.0 : { "error": "invalid_grant", "error_description": "..." }.
422 : validation ou règle métier
Les deux utilisent le statut 422 et la même enveloppe :
- Validation (
error_code: validation_failed) : la requête est mal formée — un champ obligatoire est absent, un identifiant n'existe pas dans votre organisation, une valeur est hors limites — ou elle comporte une clé que l'endpoint ne prend pas en charge. L'API est stricte : tout paramètre de requête et tout champ du corps situé hors du contrat documenté d'un endpoint est refusé et nommé danserrors, de sorte qu'une faute de frappe ne peut jamais être ignorée silencieusement. Trois phrases vous indiquent de quel type il s'agit :- inconnu —
"`nmae` n'est pas un paramètre de ce point d'accès." - lecture seule —
"`total` est en lecture seule ; le serveur le calcule."(attributs de réponse renvoyés dans une mise à jour) - renommé —
"`start_date` n'est pas un paramètre de ce point d'accès ; utilisez `date_from`."Les clés imbriquées sont signalées par leur chemin réel (items.1.total).organization_idest un paramètre de contexte, toujours accepté.
- inconnu —
- Règle métier (
error_code: business_rule_violation, ou le code propre à l'endpoint) : la requête est bien formée mais refusée — paiement supérieur au solde dû, refacturation d'une dépense non refacturable, document non éligible à VeriFactu. Lorsqu'un seul champ est en cause, il est nommé danserrors, par exempleerrors.amount.
Ne renvoyez pas une requête 422 à l'identique ; corrigez-la d'abord.
Introuvable ou pas à vous
Un 404 sur une ressource dont vous pensez qu'elle existe signifie généralement qu'elle appartient à une autre organisation que celle sélectionnée par votre jeton ou l'en-tête X-Organization-Id. L'API ne distingue volontairement pas « n'existe pas » de « ne vous appartient pas ». Il en va de même pour les identifiants envoyés dans le corps d'une requête : un identifiant d'une autre organisation échoue à la validation exactement comme un identifiant inexistant.