Rate limiting et résilience

Les limites de requêtes sont des règles d’exploitation transverses aux API. Elles ne doivent pas être confondues avec une erreur d’authentification ni avec un rejet métier propre au Flow Service, au Directory Service ou à une autre famille d’API.

429 Too Many Requests

Un 429 indique que la fréquence ou le volume d’appels a dépassé une limite applicable à l’accès utilisé.

Il ne signifie pas que le client_id, le client_secret ou l’access token sont invalides. Une erreur de credentials doit être traitée comme un problème d’authentification, généralement signalé par 401 Unauthorized.

Sur la SANDBOX, certains accès sont actuellement documentés avec les limites suivantes :

• 60 requêtes par minute ;
• 1 000 requêtes par jour.

Ces valeurs peuvent dépendre de l’environnement, du partenaire, du tenant ou du profil d’accès et peuvent évoluer.

Ce que doit faire le client

Après un 429 :

1. interrompre les nouvelles tentatives immédiates ;
2. respecter l’en-tête Retry-After lorsqu’il est présent ;
3. reprendre avec une temporisation croissante et du jitter ;
4. limiter le nombre de tentatives ;
5. réduire durablement la fréquence de polling ou la taille des traitements si le problème se répète.

Pour une opération qui modifie l’état du système, vérifier également les règles d’idempotence et de reprise propres à l’endpoint avant de rejouer la requête.

Ce qu’il ne faut pas faire

Ne relancez pas immédiatement la même requête en boucle et ne tentez pas de résoudre un 429 en renouvelant ou en changeant les credentials.

Une boucle de retry agressive :

• augmente la charge ;
• prolonge le blocage ;
• complique le diagnostic ;
• peut consommer inutilement le quota journalier.

Rate limiting et protections de sécurité

Le 429 décrit ici correspond aux limites d’utilisation documentées des API.

Les mécanismes de protection contre les abus, scans, attaques automatisées ou dénis de service sont distincts. Ils peuvent appliquer d’autres règles de blocage et leurs seuils ou critères ne sont pas exposés dans la documentation d’intégration.

Polling

Un polling mal dimensionné est une cause classique de surconsommation.

Préférez :

• des recherches différentielles ;
• une fréquence adaptée au besoin métier ;
• des fenêtres de recherche maîtrisées ;
• la pagination ;
• la réutilisation des tokens OAuth2 pendant leur durée de vie.

À journaliser en cas de 429

Conservez au minimum :

• date et heure ;
• endpoint ;
• tenant ou organisation concernée ;
• code HTTP ;
• identifiant de corrélation disponible ;
• nombre d’appels réalisé autour de l’incident.

Ne journalisez jamais les secrets ni les access tokens.

➡️ Résilience, observabilité et sécurité