Facturino / Documentation / Limitation de débit

Limitation de débit

L'API Facturino impose une limitation de débit par clé API pour protéger la plateforme contre les abus et garantir la stabilité du service. Chaque requête retourne des headers indiquant votre quota restant — surveillez-les pour anticiper un dépassement.

Limites par plan

Plan Débit (req/min) Quota mensuel Webhooks Stockage
Gratuit 100 1 000 — 100 Mo
Essential 300 10 000 5 1 Go
Pro 1 000 50 000 20 10 Go

Les limites s'appliquent par clé API et par minute glissante. En mode test (fac_test_), les requêtes GET sont exemptées de la limite par minute, et toutes les requêtes test sont exemptées du quota mensuel — le bac à sable (sandbox) est illimité. Les appels internes de warmup et de santé sont également exemptés.

Headers retournés

Chaque réponse inclut trois headers pour suivre votre consommation :

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1709891260
X-Request-Id: req_8a3b9f2e1d
HeaderSignification
X-RateLimit-LimitLimite nominale de la fenêtre courante (60 secondes)
X-RateLimit-RemainingRequêtes restantes avant blocage
X-RateLimit-ResetTimestamp Unix (secondes) à partir duquel le compteur sera réinitialisé
X-Request-IdIdentifiant unique de la requête (à fournir au support)

Réponse 429

Au dépassement, l'API retourne 429 Too Many Requests avec un header Retry-After :

HTTP/1.1 429 Too Many Requests
Retry-After: 24
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1709891260

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 24 seconds.",
    "hint": "Slow down your request rate or upgrade your plan.",
    "request_id": "req_..."
  }
}

Le header Retry-After indique le nombre de secondes à attendre. C'est une consigne ferme — ne retentez pas avant la fin du délai, sinon vous risquez un blocage prolongé.

Stratégie de retry recommandée

Respectez le header Retry-After en priorité ; à défaut (situation rare), utilisez un backoff exponentiel avec jitter aléatoire pour éviter les tempêtes de retry simultanées.

Node.js :

async function withRetry(fn, attempts = 5) {
  for (let i = 0; i < attempts; i++) {
    try {
      return await fn()
    } catch (err) {
      if (err.type !== 'rate_limit_error') throw err
      // Respecter Retry-After ; fallback à un backoff exponentiel
      const delay = (err.retryAfterMs ?? 2 ** i * 1000) + Math.random() * 200
      await new Promise(r => setTimeout(r, delay))
    }
  }
  throw new Error('Max retries exceeded')
}

await withRetry(() => facturino.invoices.create({ ... }))

Python :

import time, random

def with_retry(fn, attempts=5):
    for i in range(attempts):
        try:
            return fn()
        except RateLimitError as e:
            delay = (e.retry_after or 2 ** i) + random.uniform(0, 0.2)
            time.sleep(delay)
    raise Exception("Max retries exceeded")

Limites spécifiques par endpoint

Certains endpoints coûteux ont des quotas dédiés, indépendants de la limite globale. Ces limites ne s'appliquent qu'en mode production (fac_live_) ; le bac à sable (sandbox) en est exempté.

EndpointLimiteRaison
POST /v1/invoices/:id/finalize10 / minRéservation atomique de numéro
POST /v1/exports/fec5 / jourGénération FEC sur plages longues
POST /v1/customers/import2 / heureImport CSV en lot (max 10 000 lignes)
Calls PA send1 / facture (idempotence)Évite les doublons sur le portail DGFiP

Augmenter les limites

Si votre intégration nécessite un débit supérieur au plan Pro, contactez le support en précisant :

  • Le pattern de trafic attendu (pic / heure, total / jour)
  • Le cas d'usage (intégration ERP, marketplace, plateforme SaaS…)
  • Le volume mensuel de factures

Étapes suivantes