Aller au contenu
Sur cette page

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é dans errors, 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_id est un paramètre de contexte, toujours accepté.
  • 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é dans errors, par exemple errors.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.