Gestion des erreurs

L'API Facturino utilise des codes HTTP standards et retourne systématiquement un objet error structuré. Chaque erreur contient un identifiant de requête (request_id) à fournir au support pour toute investigation.

Format de réponse

Toutes les erreurs partagent la même enveloppe — un seul objet error en racine, jamais d'autres champs frères. Inspiré du modèle Stripe pour faciliter l'intégration.

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_required_field",
    "message": "Field 'customerId' is required.",
    "param": "customerId",
    "doc_url": "https://facturino.com/docs/errors#missing_required_field",
    "hint": "Either provide a customerId or inline a 'buyer' object.",
    "request_id": "req_8a3b9f2e1d"
  }
}

Détail des refus

Un refus porte toujours un code principal — c'est sur lui qu'une intégration branche, et il ne change pas. Quand ce refus repose sur plusieurs raisons, ou sur une raison plus précise que le code principal, l'enveloppe porte en plus un tableau issues.

Le champ est facultatif et additif : code, param, message et hint gardent exactement leur sens, et param continue de désigner le premier champ en cause. La clé est absente — jamais un tableau vide — quand le refus n'a rien de plus à dire. Un refus publie au plus 500 raisons, chaque message au plus 2 000 caractères : les mêmes bornes s'appliquent à la première réponse et à son rejeu par la même Idempotency-Key.

{
  "error": {
    "type": "validation_error",
    "code": "validation_error",
    "message": "Buyer territory could not be resolved (invalid_postal_code)",
    "param": "customerId",
    "request_id": "req_8a3b9f2e1d",
    "issues": [
      {
        "code": "invalid_postal_code",
        "param": "customer.address.postalCode",
        "message": "Buyer territory could not be resolved (invalid_postal_code)"
      }
    ]
  }
}

param n'est renseigné que lorsque la correspondance vaut pour toute requête : un pointeur approximatif enverrait corriger un champ qui était juste.

Les raisons proviennent du moteur de décision fiscale : territoire client non résolu, preuves de localisation insuffisantes, refus de décision. Elles sont jointes aux refus de POST /v1/tax-decisions, le seul endpoint qui prend une décision. Les documents (factures, avoirs, devis, factures récurrentes) s'adossent à une décision existante par son identifiant et ne produisent pas de raisons détaillées.

Codes HTTP

Types d'erreur

Le champ error.type classifie l'erreur — utilisez-le comme premier discriminant dans votre code. Liste exhaustive :

Codes d'erreur fréquents

Le champ error.code est le discriminant fin sous le type. Le code est aussi le fragment du doc_url retourné dans la réponse (https://facturino.com/docs/errors#<code>).

Catégories de rejet d'un dépôt

Un dépôt rejeté ou refusé porte un code normalisé dans einvoicing.rejectionCode, son auteur dans einvoicing.rejectionSource (platform, buyer ou facturino) et sa lecture dans einvoicing.rejectionCategory. Le motif brut reste verbatim dans einvoicing.rejectionReason, les notes jointes dans einvoicing.rejectionNote, séparées par des retours à la ligne. Au renvoi, ces champs sont archivés dans previousSubmissions puis remis à null. Un document ancien peut ne pas encore les porter.

La classification lit le code local, puis le code DGFiP, puis le code HTTP. REJ_ADR donne addressing_error, REJ_SEMAN donne semantic_error, REJ_SYNT et REJ_XSD donnent format_invalid, REJ_DOUBLON donne duplicate et AUTRE donne other. Les codes de motif d’Iopole sont lus de la même façon : SYNTAX_ERROR donne format_invalid, SEMANTIC_ERROR donne semantic_error, DUPLICATED_INVOICE donne duplicate et ROUTING_FAILURE donne buyer_not_in_directory (sauf quand la plateforme ne trouve pas le vendeur : unknown). HTTP 401/403 donne platform_auth, 409 duplicate, 422 format_invalid, 429 et 5xx platform_unavailable. HTTP 400 reste unknown, sauf indice d’annuaire dans le pré-contrôle Super PDP. Le statut fr:213 seul ne prouve pas une erreur sémantique. La source est enregistrée d’après le canal : plateforme pour fr:213 et les réponses HTTP, acheteur pour fr:210, fr:207 et fr:208, Facturino pour son contrôle avant dépôt.

Stratégie de retry

Tous les codes 4xx sauf 409/429 sont permanents — corrigez le payload, ne retentez pas.

Exemples

Node.js :

try {
  const invoice = await facturino.invoices.create({ /* ... */ })
} catch (err) {
  if (err.type === 'invalid_request_error') {
    console.error(`Champ invalide: ${err.param} — ${err.message}`)
  } else if (err.type === 'rate_limit_error') {
    // Retentez après le délai indiqué dans Retry-After
    await sleep(err.retryAfterMs)
  } else {
    // Toujours logguer err.requestId pour le support
    logger.error({ requestId: err.requestId, code: err.code }, err.message)
  }
}

Python :

from facturino import Facturino, FacturinoError

try:
    invoice = client.invoices.create(...)
except FacturinoError as err:
    if err.type == "invalid_request_error":
        print(f"Champ invalide: {err.param} — {err.message}")
    elif err.type == "rate_limit_error":
        time.sleep(err.retry_after_seconds)
    else:
        logger.error({"request_id": err.request_id}, err.message)

Contacter le support

Pour toute erreur inexpliquée ou un comportement inattendu, contactez le support en fournissant :

• Le request_id exact (préfixe req_) — il permet de retrouver les logs côté Facturino.
• L'horodatage de la requête (à la seconde près).
• Le payload envoyé (masquez les champs sensibles si nécessaire).

Contacter le support · best-effort (Gratuit, Essential), prioritaire (Pro).