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"
  }
}

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

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