Limites de débit de l'API

Elido limite le débit de l'API par clé, et non par espace de travail. Cela signifie que chaque intégration que vous construisez peut saturer sa propre limite sans affamer les autres. Cet article présente les limites par forfait, les en-têtes à lire et comment battre en retraite proprement.

Les chiffres#

Limites soutenues par clé :

Forfait	Par minute	Burst
Free	60	120
Pro	600	1200
Business	6000	12000

Le burst est ce que vous pouvez brièvement dépasser dans une fenêtre de 10 secondes. La limite soutenue est le plafond en régime permanent auquel le seau se remplit.

Il n'y a pas de limites par point de terminaison — un GET /v1/links compte de la même manière qu'un POST /v1/links. Les seules exceptions sont :

POST /v1/bulk-import — 5 importations actives par espace de travail à la fois.
POST /v1/links avec un slug personnalisé entrant en conflit avec un slug existant — ceux-ci comptent toujours mais ne remboursent pas le créneau en cas de conflit.
GET /v1/analytics/timeseries avec interval=second — limité à 60/minute même en forfait Business, car la requête ClickHouse sous-jacente est plus lourde.

En-têtes de réponse#

Chaque réponse de l'API inclut :

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 587
X-RateLimit-Reset: 1747386240

X-RateLimit-Reset est un horodatage Unix vous indiquant quand le seau sera à nouveau plein. Utilisez-le pour planifier les tentatives de reconnexion plutôt que des délais fixes.

À quoi ressemble une erreur 429#

Lorsque vous dépassez la limite :

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{
  "error": "rate_limited",
  "message": "API rate limit exceeded for this key",
  "retry_after_seconds": 12
}

Retry-After est en secondes. Attendez ce délai, puis réessayez. Les SDKs le font automatiquement avec un décalage aléatoire (jitter) ; si vous écrivez un client HTTP brut, faites de même.

Stratégie de backoff#

Si vous sollicitez l'API de manière intensive (une tâche ponctuelle en vrac, un remplissage historique), réglez le débit de votre client sur la limite soutenue plutôt que sur le burst. Une boucle naïve atteint le plafond de burst, puis stagne pendant 50 secondes, puis atteint à nouveau le burst — ce qui donne une moyenne inférieure à un simple lissage du débit.

Pseudocode :

const limit = 600; // per minute
const delayMs = (60 * 1000) / limit; // 100ms between requests

for (const item of items) {
  await fetch(...);
  await sleep(delayMs);
}

Ce modèle utilise 100 % de la limite avec zéro erreur 429.

Concurrence#

Les requêtes concurrentes partagent le seau. Si vous lancez 100 requêtes parallèles depuis un pool de workers sur le forfait Pro (600/min), les 100 premières réussissent instantanément ; le seau se remplit ensuite à raison de 10/sec. Votre pool de workers devrait viser un débit soutenu, et non une profondeur de file d'attente.

Par clé vs par IP#

Le seau est par clé, pas par IP. Si vous utilisez la même clé à partir de 10 machines, les 10 machines partagent la limite. Émettez une clé par machine si vous avez besoin de 10 fois plus de marge de manœuvre.

La couche IP possède une limite distincte et très généreuse (10 000/min/IP) destinée uniquement à arrêter les clients incontrôlables. Vous ne l'atteindrez jamais en utilisation normale ; si c'est le cas, la réponse est 429 avec le corps "error": "ip_rate_limited".

Les clés d'idempotence ne contournent pas la limite#

Envoyer la même Idempotency-Key de manière répétée compte toujours chaque requête dans votre seau — nous pouvons renvoyer la réponse mise en cache sans effectuer le travail sous-jacent, mais le compteur est incrémenté. Ne bouclez pas sur les clés d'idempotence comme stratégie de tentative de reconnexion.

Augmentation des limites#

Si votre cas d'utilisation nécessite réellement plus de 6000/min en continu, envoyez un e-mail à support@elido.app avec :

Votre identifiant d'espace de travail.
Le nom de l'intégration.
Le débit de requêtes prévu en régime permanent et en pic.
Quels points de terminaison (afin que nous puissions planifier la capacité pour les plus lourds).

Nous accordons des augmentations de limite par clé aux clients entreprise sous contrat, généralement sous un jour ouvré.

Dépannage#

Obtention soudaine d'erreurs 429 sur une clé qui fonctionnait auparavant. Soit votre code a commencé à boucler (cas le plus courant), soit quelqu'un d'autre sur l'espace de travail a commencé à utiliser la même clé. Consultez l'onglet Usage de la clé API dans le tableau de bord pour voir un graphique par minute.

Erreurs 429 sur la première requête de la journée. Les seaux du niveau Free se réinitialisent sur une fenêtre glissante, et non à minuit UTC. Si vous avez testé la limite hier à 23h59 et qu'elle ne s'est pas complètement remplie à 00h01, le premier burst est toujours limité. Attendez 60 secondes.

X-RateLimit-Remaining est négatif. Dépassement de burst. Le nombre vous indique à quel point vous êtes dans le négatif ; multipliez par 60/limit pour obtenir les secondes jusqu'au retour à zéro.