Limites de requêtes et de fréquence
Les limites qu’Elium applique aux requêtes de l’API, comment lire le coût d’une requête dans chaque réponse et que faire quand Elium refuse une requête.
L’API d’Elium a des limites qui protègent la plateforme contre les requêtes et les intégrations trop gourmandes. Il en existe deux sortes :
- Les limites de requête : ce qu’une seule requête peut demander.
- Les limites de fréquence : le nombre de requêtes qu’une intégration peut envoyer sur une période donnée.
Un usage normal reste bien en deçà des deux. Cette page explique comment savoir où vous en êtes et que faire quand Elium refuse une requête.
Limites de requête
Avant d’exécuter une requête, Elium évalue son coût. Une requête qui en demande trop est refusée sans être exécutée.
Consulter la clé extensions
Chaque réponse contient une clé extensions à côté de data. Son objet complexity donne trois valeurs pour votre requête, et le maximum de chacune. Voici la réponse de la requête { me { id } }, celle du démarrage rapide :
{
"data": {
"me": {
"id": "..."
}
},
"extensions": {
"complexity": {
"score": 2,
"depth": 3,
"resolvers": 1,
"max_score": 2000,
"max_depth": 15,
"max_resolvers": 1000
}
}
}
scoreestime le travail que demande la requête. Il augmente avec les champs qui chargent d’autres objets et avec les longues listes.depthcompte les niveaux d’imbrication de la requête.resolverscompte les champs qui chargent un autre objet.
Lisez ces valeurs pendant que vous construisez une requête, et veillez à ce que chacune reste sous son maximum. Une requête qui dépasse un maximum peut être refusée à tout moment, même si elle fonctionne aujourd’hui.
Ces limites s’appliquent aux queries (les opérations de lecture). Les mutations ne sont pas évaluées de cette façon, mais restent soumises aux limites de fréquence décrites plus bas.
Taille des pages
Pour les listes, first ou last fixent la taille d’une page, de 1 à 100. Certains filtres qui acceptent une liste d’identifiants (de tags, par exemple) ont aussi un maximum. Pour obtenir plus d’éléments, paginez : demandez 100 éléments, puis passez le curseur du dernier élément dans after pour obtenir les 100 suivants.
Champs coûteux
La plupart des champs coûtent peu. Quelques-uns demandent beaucoup de travail au serveur et font monter le score bien plus que les autres :
- Les questions posées à l’IA, comme
me.answer.answer(query:). - Les traductions automatiques d’une story.
- Les statistiques d’utilisation de la plateforme, d’un espace ou d’une story.
Ne demandez ces champs que si vous en avez besoin. Posez une seule question à l’IA par requête : pour en poser plusieurs, envoyez plusieurs requêtes.
Limites de fréquence
Elium peut aussi limiter le nombre de requêtes qu’une intégration envoie sur une période donnée, et le nombre de requêtes simultanées. Ces limites s’appliquent aux queries comme aux mutations. Elium ne les publie pas, et elles peuvent changer.
Pour les respecter :
- Envoyez les requêtes l’une après l’autre, pas en parallèle.
- Laissez un court délai entre deux mutations, surtout quand vous créez ou modifiez beaucoup de stories.
- N’interrogez pas l’API en boucle pour détecter des changements. Lisez les données quand vous en avez besoin.
- Gardez en cache les résultats qui changent peu, comme la liste des espaces.
Quand Elium refuse une requête
| Réponse | Cause | Que faire |
|---|---|---|
HTTP 400, une erreur qui cite complexity, depth ou resolvers | La requête en demande trop | Modifiez la requête (voir plus bas). La renvoyer telle quelle donne la même erreur. |
| HTTP 400, une erreur qui cite un argument | Un argument dépasse son maximum, par exemple first au-delà de 100 | Réduisez la valeur et paginez. |
| HTTP 429 | Trop de requêtes | Attendez, puis renvoyez la requête. |
Corriger une requête trop gourmande
L’objet extensions.complexity est toujours présent dans la réponse : vous savez donc quelle valeur réduire. Ensuite :
- Divisez la requête en plusieurs requêtes plus petites.
- Demandez moins d’éléments par liste, et paginez.
- Retirez les champs que vous n’utilisez pas, surtout ceux d’IA, de traduction et de statistiques.
- Évitez d’imbriquer des listes dans des listes, comme les tags de chaque story de chaque espace.
Réessayer après un trop grand nombre de requêtes
Quand vous recevez une réponse HTTP 429, arrêtez d’envoyer des requêtes pendant un moment :
- Si la réponse contient un en-tête
Retry-After, attendez au moins ce nombre de secondes. - Sinon, attendez au moins une minute.
- Si la requête suivante est encore refusée, allongez l’attente à chaque essai, par exemple en la doublant, et abandonnez après quelques tentatives.
N’insistez pas tant qu’Elium refuse vos requêtes. Les suivantes seront refusées elles aussi, et Elium peut bloquer une intégration qui continue d’essayer.
Évolution de ces limites
Elium peut modifier ces limites à tout moment, sans préavis. Si une requête, un jeton ou une intégration met la plateforme en danger, Elium peut refuser la requête ou bloquer le jeton ou l’intégration, même si les limites décrites ici sont respectées. Si votre intégration doit dépasser ces limites, contactez le support d’Elium avant de la développer.