Comment lire les erreurs renvoyées par l'API ?

Toute erreur est un document RFC 9457 (application/problem+json) : type, title, status, detail, instance, et parfois remediation et rule. Branchez votre logique sur type ; affichez detail tel quel à l'utilisateur, il est rédigé en français pour lui.

La forme

{
  "type": "…/seller_vat_number_required",
  "title": "Requête invalide",
  "status": 422,
  "detail": "Votre numéro de TVA intracommunautaire est obligatoire…",
  "instance": "/v1/invoices/…/issue",
  "remediation": "…",
  "rule": "BR-CO-17"
}

Champ	Usage
type	Adresse stable qui se termine par le code d'erreur. C'est sur lui qu'on branche.
title	Résumé court, peut être reformulé.
status	Le statut HTTP.
detail	Explication en français, à réafficher telle quelle. Peut être reformulée sans préavis.
instance	Le chemin de la requête fautive.
remediation	Facultatif : l'action suggérée, lisible par une machine.
rule	Facultatif : la règle de la norme EN 16931 en cause.

Les statuts usuels

Statut	Sens
400	Requête mal formée (JSON illisible, date invalide)
401	Authentification absente ou invalide
403	Droit manquant, société non rattachée, conditions ou double authentification attendues
404	Ressource inexistante (le detail nomme la ressource : devis, client, facture…)
409	L'état interdit l'opération (facture déjà émise, dernier propriétaire…)
422	Règle métier ou fiscale non respectée
429	Plafond de débit dépassé
500	Erreur interne, jamais détaillée
503	Service tiers indisponible : réessayer

Types inconnus

La liste des type est ouverte : traitez un type inconnu d'après son status.

Pourquoi detail est en français

QInvoice s'intègre en marque blanche : vos utilisateurs doivent pouvoir lire l'erreur sans que vous ayez à la retraduire.

Mis à jour le 30 septembre 2026.