Adlead - Documentation

# Limite de requêtes (throttle)

Cette API publique permet aux partenaires et aux solutions connectées d'intégrer facilement leurs services avec notre plateforme.
Pour garantir la stabilité, la performance et l'équité d'accès, une limite de requêtes (throttling) a été mise en place pour l'API publique.
Cette limite vise à éviter les abus tout en assurant un accès continu et performant pour tous les partenaires.

# Pourquoi une limite de requêtes ?

Le throttling contrôle la fréquence des appels que chaque intégration peut effectuer. Cela permet :

  • D'optimiser les performances en évitant la surcharge de notre système.
  • De garantir la disponibilité de l'API pour tous les partenaires.
  • De protéger la plateforme contre les abus ou appels excessifs qui peuvent dégrader l'expérience pour tous.

# Politique de limitation des requêtes

Pour assurer un accès équitable, voici les limites de requêtes appliquées :

  • Nombre maximal de requêtes :
    • 60 requêtes par minute
    • 1000 requêtes par heure

Exemple

Si vous envoyez 60 requêtes à 10h05, la prochaine requête autorisée sera possible à 10h06.
Si vous envoyez 1000 requêtes entre 10h05 et 10h30, la prochaine requête autorisée sera possible à 11h05.

IMPORTANT

Si vous dépassez l'une de ces limites, l'API renverra une réponse d'erreur 429 Too Many Requests, indiquant que le nombre maximal de requêtes autorisé a été atteint.
Vous devrez alors attendre la fin de la période de renouvellement (indiquée dans le champ retry_after de la réponse) avant de pouvoir effectuer de nouvelles requêtes.

# Usage normal vs. usage abusif

Un usage normal respecte les limites de requêtes et optimise les appels pour limiter la charge sur le serveur (ex. : en utilisant le cache).
En revanche, un usage abusif peut inclure :

  • Des appels rapides successifs pour les mêmes ressources.
  • Des tentatives répétées de contournement de la limite.
  • Une fréquence élevée de requêtes durant les heures de pointe.

Pour éviter un usage abusif, respectez les entêtes X-Rate-Limit-* et suivez les recommandations pour une utilisation optimale de l'API.

# En-têtes de suivi de limitation

Les en-têtes suivants sont fournis dans chaque réponse API pour informer des limites et des tentatives restantes :

En-tête Description
X-Rate-Limit-Remaining-Minute Nombre de requêtes restantes pour la limite par minute.
X-Rate-Limit-Remaining-Hour Nombre de requêtes restantes pour la limite par heure.
X-Rate-Limit-Limit-Minute Limite maximale de requêtes autorisées par minute.
X-Rate-Limit-Limit-Hour Limite maximale de requêtes autorisées par heure.
Retry-After Temps d'attente en secondes avant de pouvoir effectuer une nouvelle requête après dépassement de la limite.

# Cas de dépassement de la limite

Lorsque le nombre de requêtes dépasse la limite définie, l'API renvoie une réponse avec le code d'erreur HTTP 429 Too Many Requests accompagnée d'une réponse JSON expliquant la raison de l'erreur.
Voici un exemple de réponse :

{
    "success": false,
    "message": "Vous avez dépassé le nombre de requêtes autorisé, veuillez réessayer dans 60 secondes. Pour en savoir plus, consultez notre documentation : https://docs.adlead.immo/v1/#limite-de-requetes-throttle",
    "retry_after": 60,
    "data": null
}
Champ Description
success Indique si la requête a été traitée avec succès (false en cas de dépassement de la limite).
message Message décrivant l'erreur, incluant un lien vers la documentation pour plus de détails.
retry_after Temps d'attente en secondes avant de pouvoir effectuer une nouvelle requête.
data Champ renvoyant null en cas d'erreur.

# Bonnes pratiques pour gérer le throttle

Pour une utilisation efficace de l'API publique et pour éviter de déclencher la limite de requêtes, voici quelques recommandations :

# 1. Suivre le champ retry_after et les en-têtes X-Rate-Limit-*

Les en-têtes X-Rate-Limit-Remaining-Minute et X-Rate-Limit-Remaining-Hour indiquent le nombre de requêtes restantes pour chaque période de limite (par minute et par heure).
Le champ retry_after présent dans la réponse, ainsi que dans l'en-têtes Retry-After, vous indique le temps d'attente avant la prochaine requête autorisée.
En respectant ces en-têtes, vous pouvez éviter de recevoir des réponses en 429 répétées et planifier les nouvelles tentatives après le délai recommandé.

# 2. Utiliser le caching

Pour limiter les appels inutiles à l'API, mettez en cache les données fréquemment consultées (par exemple, informations programme, détail du stock).
Cette technique réduit la charge sur l'API et améliore les performances de votre application.

# 3. Regrouper les requêtes

Si possible, regroupez vos requêtes en un seul appel API au lieu de faire des appels successifs pour chaque ressource.
Par exemple, si vous devez récupérer des informations sur plusieurs lots ou documents, utilisez la route /lots Détails.

# 4. Effectuer les requêtes en heures creuses

Pour minimiser l'impact de vos requêtes sur notre infrastructure, planifiez les appels massifs durant les heures creuses (entre 23h00 et 06h00).
Cela réduit le risque de rencontrer des erreurs 429 et peut améliorer la vitesse de traitement de vos requêtes.

# 5. Utiliser les webhooks pour réduire les appels inutiles

Si votre intégration nécessite de suivre des événements ou des mises à jour, envisagez d'utiliser notre système de webhooks. Les webhooks vous permettent de recevoir automatiquement des notifications lorsqu'un événement se produit, sans devoir interroger l'API en continu.

Cela offre plusieurs avantages :

  • Réduction des appels redondants : Au lieu de vérifier fréquemment les mises à jour, vous recevez une notification uniquement lorsqu'un événement pertinent a lieu.
  • Amélioration des performances : Les webhooks minimisent l'usage de votre quota de requêtes et réduisent la charge sur l'API.
  • Réactivité accrue : En étant alerté en temps réel des changements, votre application peut réagir immédiatement sans attendre la prochaine requête planifiée.

Pour en savoir plus sur la configuration des webhooks et leur utilisation, consultez notre documentation sur les webhooks.

# Usage des routes /lots et /allotments

Les routes /lots et /allotments sont particulièrement consommatrices en ressources, car elles renvoient un grand volume de données.
Leur usage doit donc être raisonné afin de préserver la performance et la stabilité de l'API.

Avant d'implémenter une récupération automatique, nous vous invitons à :

# 1. Limiter la fréquence des appels

Les grilles de lots évoluent peu fréquemment au cours d'une journée. Il est donc inutile d'interroger l'API en continu, un rafraîchissement quotidien est généralement suffisant.
Nous demandons de ne pas programmer plus que quelques appels par programme par jour, idéalement en dehors des heures de forte activité.

# 2. Utiliser les webhooks pour la mise à jour en temps réel

Pour suivre les changements (mise à jour des stocks, nouveaux lots, modification de prix, etc.), exploitez notre système de webhooks.
Les webhooks vous informent automatiquement lorsqu'un changement survient, ce qui évite d'interroger l'API à intervalles réguliers.

IMPORTANT

Un usage abusif de cette route peut entraîner des restrictions sur votre clé API.

# Erreurs courantes et dépannage

# 1. Erreur 429 Too Many Requests

Cause : Dépassement de la limite de requêtes autorisées Lien vers la politique de limitation des requêtes.
Solution : Attendez le délai indiqué dans le champ retry_after avant de renvoyer une nouvelle requête. Vérifiez également si votre code peut réduire le nombre de requêtes en utilisant des caches ou en regroupant les appels.

# 2. Erreur de réponse lente

Cause possible : Trop de requêtes envoyées en peu de temps.
Solution : Étalonnez la fréquence d'appel pour éviter des pics de requêtes et améliorez l'optimisation côté client avec le cache.

← Clé API →