Gérer les limites de débit

01En une phrase #sec_56b85c74

Trois compteurs indépendants gouvernent le débit — les données, les preuves, les jetons — et certains appels en consomment deux à la fois.

02Les trois plafonds #sec_0a236919

Ce sont des valeurs par défaut, pas des constantes : votre souscription peut porter un plafond relevé. Un relèvement accordé par l'éditeur prend effet dès la requête suivante, sans redémarrage ni délai de propagation.

03Le compteur des preuves s'ajoute, il ne remplace pas #sec_4b9c7978

C'est le point qui surprend le plus. Un appel à evidence décrémente les deux compteurs : celui des preuves et le standard. Un client qui ne ferait que des appels de preuves serait donc arrêté à soixante par minute, pas à six cents.

La raison est mesurable : chaque appel de preuve produit un PDF et le signe , soit environ 325 ms de processeur et de cryptographie. Au plafond commun, un seul client aurait consommé près de 40 % de la machine ; à soixante par minute, environ 4 %. Le plafond distinct existe pour que la lenteur d'un intégrateur ne devienne pas la lenteur de tout le monde.

04Ce qui est compté, et pour qui #sec_f6c8dcbb

Le compteur est attaché au client authentifié , pas à l'adresse IP. Deux processus qui partagent un client_id partagent son plafond, où qu'ils tournent ; deux clients distincts sur la même machine ont chacun le sien.

Le point d'appel de jetons fait exception avant l'authentification : n'ayant pas encore de client, il compte par adresse IP.

Conséquence pratique : si plusieurs intégrations doivent vivre côte à côte, donnez à chacune son propre client plutôt que de partager un secret. Elles cesseront de se gêner, et un dépassement désignera la coupable.

05Le refus #sec_7af04e67

Un dépassement rend 429 Too Many Requests , avec un en-tête Retry-After et un corps application/problem+json .

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "type": "https://docs.reviewit.example/problems/rate-limit",
  "title": "Too many requests",
  "status": 429,
  "detail": "The rate limit for this client has been exceeded. Retry after the indicated delay.",
  "instance": "/api/v1/evidence/4821"
}

instance porte le chemin refusé : sur une intégration qui appelle plusieurs domaines, c'est ce champ qui dit lequel a dépassé.

06Réessayer #sec_41e4809f

Le plafond est une fenêtre fixe d'une minute , pas un débit lissé. Le compteur repart de zéro au début de chaque minute, il ne se recharge pas progressivement.

Attendez le délai indiqué par Retry-After . Réessayer avant ne fait que consommer la fenêtre suivante, et un client qui boucle sans attendre reste bloqué indéfiniment tout en faisant croire à une panne.

Il n'y a pas de file d'attente. Un appel au-delà du plafond est refusé immédiatement, il n'est pas mis en attente. C'est délibéré : une réponse rapide qui dit non est plus utile qu'une réponse lente qui finit par dire oui, parce qu'elle laisse au client le choix de ralentir.

07Rester sous le plafond #sec_767baf63

Trois gestes, dans l'ordre où ils rapportent.

Le premier : garder le jeton . Un jeton vit une heure ; en redemander un à chaque appel épuise le plafond de jetons — le plus bas des trois — bien avant celui des données.

Le deuxième : monter la taille de page plutôt que multiplier les appels. Cinq cents éléments en une requête coûtent un jeton de débit ; les mêmes cinq cents en cinq requêtes en coûtent cinq.

Le troisième : espacer les preuves . Elles ont leur propre plafond et consomment aussi le standard ; les regrouper en rafale est le moyen le plus rapide de heurter les deux.

08À retenir #sec_2dde19f8

Six cents appels par minute, soixante pour les preuves qui s'ajoutent au standard, soixante pour les jetons. Un compteur par client authentifié. Un refus immédiat, jamais une file d'attente. Et Retry-After qui dit exactement combien de temps attendre.