Limites de requêtes (rate limiting)

L'API Certificall limite le nombre de requêtes acceptées sur une fenêtre glissante de 60 secondes. Au-delà, elle répond 429 Too Many Requests.

Comment les requêtes sont comptées

Les requêtes sont comptées par entreprise et par endpoint.

Trois conséquences utiles à connaître :

• Vos appels ne sont pas pénalisés par ceux des autres partenaires. Votre limite vous est propre.
• Appeler depuis plusieurs serveurs ne divise pas votre limite, et ne la multiplie pas non plus : c'est votre entreprise qui est comptée, pas l'adresse IP d'origine.
• Chaque endpoint a son propre compteur. Saturer GET /cases n'entame pas la limite de PATCH /cases/update.

Sur les endpoints publics qui ne demandent pas d'authentification (partage de dossier, images, médias), l'entreprise ne peut pas être identifiée : les requêtes n'y sont donc pas comptées par entreprise. Ces endpoints sont dimensionnés en conséquence, avec des limites nettement plus hautes.

remarque

Les requêtes rejetées pour un autre motif (droits insuffisants, dossier inconnu…) sont aussi comptées. Une boucle qui échoue peut donc déclencher un 429.

Limites par endpoint

Endpoint	Limite (par minute)
POST /certificall/api/auth/token	200
GET /certificall/api/cases	5
POST /certificall/api/cases/bulk-create	10 (jusqu'à 50 dossiers par appel)
PATCH /certificall/api/cases/bulk-update	10 (jusqu'à 100 dossiers par appel)
POST /certificall/api/cases/bulk-delete	10 (jusqu'à 50 dossiers par appel)
POST /certificall/api/reports/report/:reportToken	25
GET /certificall/api/reports/:reportToken	100
GET /certificall/share/case/:shareToken	180
GET /certificall/images/:imageUrl	500
GET /certificall/medias/video/:videoUrl	500
Tous les autres endpoints (dont PATCH /certificall/api/cases/update)	60

La réponse 429

Code statut : 429 Too Many Requests

{
  "statusCode": 429,
  "message": "Rate limit exceeded: max 60 requests per 60s on this endpoint. Retry after 42s.",
  "requestId": "b3f1c2e4-...",
  "method": "PATCH",
  "path": "/certificall/api/cases/update",
  "timestamp": "2026-08-13T09:12:34.567Z",
  "name": "ApiError",
  "details": {
    "header": "Error on request: b3f1c2e4-..."
  }
}

En-têtes de la réponse :

En-tête	Signification
Retry-After	Nombre de secondes à attendre avant de réessayer
X-RateLimit-Limit	Nombre de requêtes autorisées sur la fenêtre
X-RateLimit-Remaining	Requêtes restantes (0 sur un 429)
X-RateLimit-Reset	Secondes avant remise à zéro du compteur

Les en-têtes X-RateLimit-* sont également présents sur les réponses acceptées : vous pouvez suivre X-RateLimit-Remaining pour ralentir avant d'être bloqué.

Conduite à tenir

1. Respectez Retry-After. Réessayer immédiatement ne fait qu'ajouter des requêtes au compteur.
2. Surveillez X-RateLimit-Remaining et espacez vos appels quand il approche de zéro.
3. Privilégiez les endpoints de masse plutôt que les boucles. Pour créer, mettre à jour ou supprimer plusieurs dossiers à la suite, utilisez la création en masse, la mise à jour en masse ou la suppression en masse : chacune ne compte que pour une seule requête, là où une boucle en compte autant qu'elle contient de dossiers. À défaut d'endpoint de masse pour votre besoin, étalez les requêtes sur la fenêtre plutôt que de les envoyer d'un bloc.

Exemple de gestion du 429 :

async function callWithRetry(request, maxAttempts = 3) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const response = await request();
    if (response.status !== 429) return response;

    const retryAfter = Number(response.headers.get('Retry-After')) || 60;
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
  }
  throw new Error('Limite de requêtes toujours dépassée après plusieurs tentatives');
}

Besoin d'une limite plus haute ?

Si votre intégration atteint régulièrement ces limites, contactez-nous : elles peuvent être ajustées selon votre usage.