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 le quota est compté

Le quota est compté par entreprise et par endpoint.

Deux conséquences utiles à connaître :

• Vos appels ne sont pas pénalisés par ceux des autres partenaires. Votre quota vous est propre.
• Appeler depuis plusieurs serveurs ne divise pas votre quota, et ne le 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 ne consomme pas le quota 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 : le quota n'y est donc pas cloisonné 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…) consomment aussi du quota. 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
PATCH /certificall/api/cases/bulk-update	10 (jusqu'à 100 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 que consommer davantage de quota.
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 mettre à jour plusieurs dossiers à la suite (par exemple propager une date de planification), utilisez la mise à jour en masse : elle ne compte que pour une seule requête, là où une boucle en consomme 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('Quota toujours dépassé après plusieurs tentatives');
}

Besoin d'une limite plus haute ?

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