Rate limiting
L'API Cocolis applique une limite de débit pour protéger l'infrastructure. Cette limite s'applique à toutes les routes de l'API, y compris can_match et la création d'annonces.
Limites en vigueur
Les limites sont comptabilisées par application partenaire — identifiée par votre clé d'API ou par votre token d'authentification. Pour les requêtes non authentifiées (connexion, création de compte), elles sont comptabilisées par adresse IP.
| Périmètre | Limite |
|---|---|
Toutes les routes /api, quelle que soit la méthode HTTP | 600 requêtes par minute |
Toutes les routes /api, en authentifié | 5 000 requêtes par heure |
Connexion (POST /api/v1/auth/sign_in, /api/v1/app_auth/sign_in) | 60 requêtes par minute |
Création de compte (POST /api/v1/auth, POST /api/auth/guest) | 2 requêtes par minute |
Limites spécifiques à certains endpoints
Quelques endpoints renvoient des volumes de données importants et sont coûteux à calculer. Ils sont soumis à une limite dédiée, plus basse que les limites générales ci-dessus :
| Endpoint | Limite |
|---|---|
GET /api/v1/rides/mine | 20 requêtes par minute (en moyenne 1 toutes les 3 secondes) |
Ces limites s'ajoutent aux limites générales : un parcours complet de vos annonces doit donc être étalé dans le temps.
Réponse en cas de dépassement
Lorsque la limite est atteinte, l'API renvoie un statut HTTP 429 Too Many Requests avec les headers suivants :
| Header | Description |
|---|---|
RateLimit-Limit | Limite applicable |
RateLimit-Remaining | Requêtes restantes (toujours 0 lors d'un 429) |
RateLimit-Reset | Timestamp Unix avant lequel attendre |
Retry-After | Nombre de secondes à attendre |
Le corps de la réponse contient simplement Throttled.
Bonnes pratiques
- Implémentez une logique de retry avec backoff exponentiel en vous appuyant sur le header
Retry-After. - Mettez en cache côté client les réponses qui changent rarement afin de réduire le nombre d'appels.
- Évitez les polls agressifs — préférez les webhooks pour être notifié des changements d'état.
- Ne re-parcourez pas l'intégralité de vos annonces via
GET /api/v1/rides/mine: appuyez-vous sur les webhooks pour suivre les changements d'état, et réservez ce listing à une resynchronisation ponctuelle.