Okouro limite le débit des requêtes pour garder l’API réactive pour tout le monde. Les limites utilisent une fenêtre de temps fixe et sont appliquées avant la plupart des autres traitements.

Comment les limites sont appliquées

Les requêtes sont comptées dans une fenêtre glissante. Il y a trois niveaux :

Le niveau Identifiants est volontairement strict pour ralentir les tentatives de force brute. GET /health est exempté de toutes les limites.

Les limites sont des soupapes de sécurité indicatives, pas des quotas ; les valeurs exactes sont définies par la configuration du serveur et peuvent différer des valeurs par défaut ci-dessus. Lisez-les dans les en-têtes de réponse plutôt que de les coder en dur.

En-têtes de réponse

Chaque réponse autorisée inclut votre budget actuel :

x-ratelimit-limit: 300
x-ratelimit-remaining: 297
x-ratelimit-reset: 42

• x-ratelimit-limit - le plafond pour la fenêtre.
• x-ratelimit-remaining - les requêtes restantes dans la fenêtre actuelle.
• x-ratelimit-reset - les secondes avant la réinitialisation de la fenêtre.

Quand vous êtes limité

Dépasser une limite renvoie 429 Too Many Requests avec un en-tête Retry-After :

HTTP/1.1 429 Too Many Requests
retry-after: 12
x-ratelimit-remaining: 0

{ "error": "rate_limited", "message": "Too many requests; please slow down." }

Attendez le nombre de secondes indiqué dans Retry-After, puis réessayez. Notez que le corps ici contient un champ message supplémentaire par rapport à la forme d’erreur standard.

Le niveau Identifiants fait exception : pour ne pas révéler le seuil anti force brute, une requête d’identifiants limitée reçoit un corps générique et seulement un en-tête Retry-After (sans en-têtes x-ratelimit-*) :

HTTP/1.1 429 Too Many Requests
retry-after: 12

{ "error": "too many attempts; please try again later" }

Verrouillage de compte

Les points d’entrée d’identifiants (/auth/login, /auth/register, /auth/refresh, acceptation d’invitation et échange de changement de mot de passe) sont en plus protégés par un verrouillage par compte, indépendant de l’IP. Après un petit nombre d’échecs de connexion consécutifs sur un même compte, ce compte est temporairement verrouillé et renvoie 429 Too Many Requests avec un en-tête Retry-After, même depuis des adresses IP différentes. Une connexion réussie lève le verrouillage. Cela complète la limitation par IP décrite plus haut ; cela ne la remplace pas.

Le corps est le même message générique « too many attempts » que la limitation Identifiants ci-dessus, afin qu’un compte verrouillé ne se distingue pas d’une IP limitée.

Rester sous la limite

• Regroupez les lectures avec la pagination. Récupérez des pages plus grandes (per_page jusqu’à 100) plutôt que beaucoup de petites pages. Voir Conventions.
• Mettez en cache ce qui change rarement. Les données de référence comme les clients et les consultants n’ont pas besoin d’être récupérées à chaque opération.
• Respectez Retry-After sur 429. Bombarder un point d’entrée limité vous maintient limité ; réduire le rythme lève la limite.
• Authentifiez-vous. Le trafic authentifié est indexé par utilisateur, donc une intégration très active n’épuise pas le budget d’une autre, et cela évite le compartiment d’IP public partagé.

Comportement en mode fail-open

Si le magasin de données du limiteur de débit est indisponible, les requêtes vers les routes API ordinaires sont laissées passer plutôt que bloquées. Les points d’entrée d’identifiants basculent alors vers un limiteur local au processus, afin que la protection contre la force brute sur la connexion ne soit pas totalement perdue pendant une panne. Dans tous les cas, considérez les limites comme une protection au mieux, pas une garantie, et concevez quand même votre client pour bien se comporter sous 429.