Limites de débit

Certivant applique une limite de débit de l'API par minute pour protéger la plateforme contre les clients incontrôlés et les voisins bruyants. Restez sous la limite et vous ne verrez jamais de limitation ; si vous la dépassez, vous recevez un 429 accompagné d'en-têtes qui indiquent exactement quand réessayer.

La limite

Votre plafond par minute est défini par votre forfait. L'opérateur de la plateforme peut aussi accorder une exception par client, toujours plafonnée au maximum du forfait. Le nombre effectif est celui que signale l'en-tête X-RateLimit-Limit sur chaque réponse : lisez-le plutôt que de coder une valeur en dur.

Plafonds par défaut selon le forfait

Il s'agit de valeurs par défaut : l'opérateur de la plateforme peut ajuster le plafond de chaque forfait et accorder à votre organisation une limite plus élevée par client (jusqu'au plafond du forfait). Vous pouvez consulter la limite effective de votre organisation, en lecture seule, dans le tableau de bord, à KYC → Développeur.

Si vous avez besoin d'un plafond plus élevé pour le trafic de production, demandez à votre interlocuteur de compte (ou, sur les déploiements auto-hébergés, à l'opérateur de votre plateforme) de relever le plafond de votre forfait ou votre limite par client.

En-têtes de réponse (sur chaque réponse authentifiée)

Chaque réponse réussie contient l'état actuel de la limite de débit :

HTTP/1.1 200 OK
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 42
Content-Type: application/json

{ "data": [...], "pagination": {...} }

Lisez ces valeurs dans votre client pour ralentir de façon proactive : n'attendez pas un 429 si vous voyez X-RateLimit-Remaining: 3.

La réponse 429

Lorsque vous dépassez la limite, la requête suivante renvoie :

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 18
Content-Type: application/json

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Max 120 requests per 60s. Retry in 18s."
  }
}

X-RateLimit-Reset indique exactement combien de temps attendre. Utilisez-le plutôt que de deviner.

Stratégie de nouvelle tentative

Le gestionnaire le plus simple et correct :

async function withRateLimit<T>(fn: () => Promise<Response>): Promise<T> {
  while (true) {
    const res = await fn();
    if (res.status !== 429) {
      if (!res.ok) throw await readError(res);
      return res.json() as Promise<T>;
    }
    const retryAfterSec = Number(res.headers.get("X-RateLimit-Reset") ?? 60);
    await sleep(retryAfterSec * 1000 + 100); // pad by 100ms for clock skew
  }
}

Trois principes à respecter :

1. Respectez X-RateLimit-Reset. Attendre moins ne fait que vous heurter de nouveau à la limite.
2. Ajoutez environ 100 ms de marge pour tenir compte du décalage d'horloge entre votre machine et la périphérie de Certivant.
3. Limitez vos tentatives si la requête n'est pas critique. Insister pendant 5 minutes sur un appel de liste non urgent gaspille les ressources des deux côtés.

Concevoir en tenant compte de la limite

L'économie la plus importante vient de l'utilisation des webhooks. La première cause de tickets de support « j'atteins la limite de débit » est constituée par des intégrations qui interrogent en boucle les changements d'état : ne le faites pas, configurez plutôt des webhooks.

Comportement en cas de rafale

La limite est appliquée selon une fenêtre fixe : la première requête démarre un compteur de 60 secondes, et chaque requête est décomptée de votre plafond jusqu'à la réinitialisation de la fenêtre. Répartissez le trafic soutenu de façon homogène au lieu d'épuiser le budget de la minute dans les toutes premières secondes.

Si vous avez un schéma de rafale connu (par exemple une tâche de traitement par lot quotidienne qui traite 500 enregistrements), espacez les appels :

for (const record of records) {
  await processOne(record);
  await sleep(500); // 2 req/s — comfortably under typical ceilings
}

Que se passe-t-il lorsque Redis est injoignable

Si l'instance Redis de la limite de débit est temporairement injoignable, Certivant bascule en mode permissif : il ne bloque pas votre trafic. Vous recevez des réponses 2xx normales, sans les en-têtes X-RateLimit-*. Une fois Redis rétabli, l'application de la limite reprend normalement. Une panne de Redis de notre côté n'interrompt donc pas votre intégration.

La livraison des webhooks est distincte

La limite de débit s'applique à vos appels sortants vers Certivant. Les livraisons de webhooks entrants, de Certivant vers votre point de terminaison, ne consomment aucun quota. Il n'existe pas de « limite de débit des webhooks » dont vous devriez vous soucier.

Points de terminaison publics

Les points de terminaison qui ne nécessitent pas de clé d'API (GET /api/status, GET /api/kyc/public/status, les points de terminaison de soumission de formulaires) disposent d'une limite distincte par adresse IP de 60 requêtes par minute. Elle s'applique à l'adresse IP de l'appelant, et non à une clé d'API. Elle est volontairement restrictive, car ces points de terminaison sont accessibles sans authentification ; si votre interface destinée aux demandeurs l'atteint, faites plutôt passer les appels par votre propre backend afin qu'ils partagent une adresse IP que vous contrôlez.