Limites de débit
Une limite de débit définit le nombre maximum de requêtes qu'une application peut adresser à l'API dans une période de temps donnée. Ce mécanisme est essentiel pour maintenir la santé globale et la fiabilité des services.
Pourquoi nous utilisons la limitation de débit
- Empêche un seul client de surcharger les serveurs avec un nombre excessif de requêtes.
- Garantit des temps de réponse cohérents et prévisibles pour tous les clients.
- Protège les services back-end contre les pics de trafic inattendus.
- Maintient un schéma de charge stable et contrôlé sur l'infrastructure.
- Renforce la défense contre les tentatives d'attaque, telles que la force brute.
- Atténue le risque d'attaques par déni de service distribué (DDoS).
- Réduit l'impact causé par des intégrations mal implémentées.
- Limite les dommages potentiels résultant de la compromission d'identifiants API.
- Assure un accès équilibré aux ressources API pour tous les clients.
- Empêche que l'utilisation abusive de certains ne dégrade l'expérience des autres utilisateurs.
- Permet de prioriser le trafic selon des critères et des besoins métiers.
- Encourage des pratiques de consommation API plus efficaces et durables.
Fonctionnement de la limitation de débit
Chaque appel API est comptabilisé dans la limite de requêtes par seconde autorisée. La valeur par défaut est de 10 RPS par tenant. Lorsque la limite est dépassée, l'API retourne HTTP 429 Too Many Requests.
Les limites exactes sont configurées par tenant. Contactez votre équipe d'intégration pour confirmer les limites appliquées à votre compte avant de dimensionner des intégrations à fort débit.
Gestion des erreurs 429
Si votre activité va connaître une augmentation du volume de requêtes (temporairement ou de manière permanente), notifiez l'équipe Unico afin d'augmenter la limite de débit pour votre environnement. Cette demande doit être faite avant que le volume n'augmente réellement, pour éviter que votre application ne devienne inopérante.
- Auditez votre code pour identifier les modèles d'utilisation inefficace de l'API.
- Vérifiez les boucles non intentionnelles ou les appels API redondants.
- Répartissez les requêtes plus uniformément dans le temps au lieu de les envoyer par grandes rafales.
- Mettez en cache les données fréquemment consultées qui changent rarement.
- Utilisez le jeton d'accès OAuth2 pendant toute sa durée de vie d'1 heure — n'appelez pas
POST /oauth2/tokenpar requête. - Implémentez des stratégies d'invalidation de cache appropriées.
Abonnez-vous aux Webhooks et événements pour PROCESS_STATE_FINISHED plutôt que de faire du polling sur GET /client/v1/process/\{id\}. Une boucle de polling peut facilement épuiser le budget de GET-process en cas de fort trafic.
Ce qui se passe lorsque vous atteignez la limite
La plateforme retourne :
HTTP/1.1 429 Too Many Requests
Retry-After: 12
| En-tête | Signification |
|---|---|
Retry-After | Nombre de secondes à attendre avant de réessayer. Respectez-le. |
Si Retry-After est absent, utilisez un backoff exponentiel (1s, 2s, 4s, 8s, …) plafonné à 60s.
Considérations sur la concurrence
Les limites de débit plafonnent les requêtes par minute, mais la plateforme dispose également de plafonds de concurrence au niveau de l'infrastructure. Même si vous avez un budget pour 100 requêtes/minute, envoyer les 100 dans la même seconde est plus susceptible d'être rejeté que de les répartir sur la minute.
Pour les intégrations à fort débit, visez un RPS régulier plutôt que des rafales.
Livraison des webhooks Magic Link
Trully a ses propres quotas de livraison pour Webhook V2. Le serveur webhook doit répondre dans 1 minute ; les réponses plus lentes sont abandonnées (le processus de l'utilisateur n'est pas affecté). Pour un traitement cohérent, acquittez le webhook rapidement et traitez-le de manière asynchrone.
Étapes suivantes
- Authentification — stratégie de mise en cache des jetons.
- Webhooks et événements — remplacer le polling par le push.
- Codes d'erreur > Politique de réessai — quand (et quand ne pas) réessayer.