En résumé : même avec un quota défini sur une clé API, les coûts peuvent dépasser le budget prévu. Cet article explique pourquoi, et découpe le contrôle budgétaire d’un essai IA en trois lignes de budget, avec un ordre d’application bien précis.
Commençons par la conclusion : le quota d’une clé sur la passerelle est un plafond souple, et en cas de requêtes concurrentes, il ne peut pas servir de plafond de facturation strict. Si l’on prend l’exemple de la documentation des jetons d’APIYI, le quota est vérifié au démarrage de la requête. Plusieurs requêtes peuvent passer le contrôle en même temps, ou une seule requête peut coûter très cher : dans les deux cas, la consommation finale peut dépasser le quota fixé.
La méthode fiable consiste à traiter le problème en trois couches :
- Le back-end de l’application effectue la vérification avant d’envoyer la requête et réserve le budget de façon atomique.
- Côté passerelle, on émet une clé séparée pour le trafic d’essai, avec un quota et une liste blanche de modèles, afin de réduire l’impact si cette clé est utilisée à mauvais escient.
- L’alerte sur le solde du compte ne sert qu’à notifier, pour déclencher une intervention humaine.
Ces trois couches ont des rôles qui ne se substituent pas les uns aux autres. Le véritable contrôle d’admission budgétaire se fait dans le registre propre à l’application.

Carte des connaissances et index : ordre et répartition des trois lignes budgétaires
Le tableau ci-dessous sert à la fois de carte des connaissances et d’index. Il indique dans quel ordre s’appliquent les trois lignes budgétaires, ce dont chacune s’occupe, pourquoi elles sont disposées ainsi, et les numéros de section correspondants.
| Ordre | Ligne budgétaire | Rôle | Pourquoi ce positionnement | Objectif | Section |
|---|---|---|---|---|---|
| Prérequis | Comprendre le quota souple | Distinguer la vérification avant requête, la pré-réservation et le débit réel | Sans une compréhension claire de la chronologie de facturation, les trois couches suivantes ne peuvent pas être conçues | Comprendre comment le dépassement se produit | 1, 1.1 |
| Première barrière | Budget du backend applicatif | Réservation et règlement atomiques par utilisateur et par pool d’essai | Seule l’application sait « qui utilise, et combien peut être utilisé » | Bloquer le dépassement avant l’envoi de la requête | 2.1, 3 |
| Deuxième barrière | Clé d’essai dédiée | Quota, liste blanche de modèles, isolation du trafic de production | En cas de bug applicatif, la passerelle constitue la deuxième frontière | Réduire la surface d’exposition d’une clé unique | 2.2 |
| Troisième barrière | Alerte sur le solde du compte | Notifier lorsque le solde passe sous un seuil | L’alerte est un signal a posteriori, sans capacité de blocage | Permettre une intervention rapide | 2.3 |
| Mise en œuvre | Registre de concurrence et vérification avant mise en production | Réservation, règlement, gestion des échecs, rapprochement, messages conviviaux | Transformer les principes précédents en un processus vérifiable | Validation point par point avant mise en production | 3, 4 |
Ordre de lecture suggéré : commencez par la section 1 pour comprendre la chronologie, puis la section 2 pour clarifier la répartition des rôles ; la section 3 est la partie implémentation. La section 4 est à utiliser séparément juste avant la mise en production, comme liste de contrôle.
À savoir : les termes indispensables avant d’aborder la ligne budgétaire
| Terme | Explication concise |
|---|---|
| Plafond souple | Le quota est contrôlé au démarrage de la requête ; une fois le contrôle passé, rien ne garantit que la consommation totale ne franchira pas la ligne |
| Pré-débit | La passerelle déduit d’abord une partie du quota sur la base d’une estimation, puis règle selon l’usage réel à la fin de la requête |
| Réservation atomique | Effectuer « vérifier le solde et l’occuper » en une seule opération indivisible, pour empêcher des requêtes concurrentes de passer simultanément |
| Réservation en vol | La part de budget encore à l’état occupé dans le registre, alors que la requête est partie et que le coût réel n’est pas encore confirmé |
| remain_quota | Champ de quota forfaitaire d’un token APIYI ; selon la documentation, 500000 correspond à 1 $ |
| Rapprochement | Vérifier un par un les journaux de la passerelle et son propre registre, pour corriger l’écart entre l’estimation et le réel |
1 Pourquoi le quota d’une clé API peut être dépassé par des requêtes concurrentes
La documentation des tokens APIYI est très claire sur ce point : le quota d’une clé est un plafond souple, contrôlé au démarrage de la requête. Des requêtes concurrentes, ou une seule requête très coûteuse, peuvent donc faire dépasser le quota défini par la consommation réelle. C’est une caractéristique de la structure de facturation « contrôle au début, règlement à la fin », sans aucun rapport avec un éventuel bug de la plateforme.
Un scénario hypothétique permet de bien le voir (les chiffres sont indicatifs, pas mesurés). Une clé d’essai dont le quota restant équivaut à 1 $ reçoit 20 requêtes au même instant. Chacune constate au démarrage que le « solde est positif » et toutes sont donc laissées passer. Quand elles se terminent les unes après les autres et sont réglées selon l’usage réel, la consommation totale a depuis longtemps dépassé 1 $. Et même sans concurrence, une seule requête à long contexte et à forte sortie peut coûter plus cher que le quota restant.
Deux idées fausses courantes méritent d’être levées :
- Le quota ne se recharge pas automatiquement chaque jour. La documentation indique que remain_quota est un quota forfaitaire unique ; un « reset quotidien » doit être mis en place côté application, avec un script planifié.
- La liste blanche de modèles ne vaut pas plafond de coût. Elle limite seulement les modèles appelables, sans contraindre le nombre d’appels d’un même modèle ni la taille de chaque appel.

1.1 Les trois moments du quota d’une clé API : contrôle avant requête, estimation et débit réel
Un appel a trois moments en matière de facturation, qui répondent chacun à une question différente :
| Moment | Où cela se passe | Question à laquelle il répond | Peut-il servir de plafond dur |
|---|---|---|---|
| Contrôle avant requête | Passerelle, au démarrage de la requête | Cette clé a-t-elle encore du quota à cet instant | Non, en concurrence plusieurs passent en même temps |
| Estimation et pré-débit | Passerelle, sur la base d’une estimation | Combien cette requête va probablement occuper | Non, l’estimation s’écarte du réel |
| Débit réel | Passerelle, à la fin de la requête | Combien cette requête a réellement consommé | Donnée a posteriori, inutilisable pour l’admission |
La documentation APIYI sur le pré-débit précise ceci : la passerelle pré-débite sur la base d’une estimation, puis règle selon l’usage réel ; ce mécanisme ne remplace pas la réservation atomique côté métier. Le pré-débit de la passerelle sert à sa propre facturation et ne sait pas combien de quota d’essai il reste aujourd’hui à l’un de vos utilisateurs. La question « cet utilisateur peut-il envoyer une requête de plus ? » ne peut donc être tranchée que par le backend de l’application.
2 Les trois lignes budgétaires d’un essai d’IA
Ces trois lignes répondent à trois types de risques : un usage excessif au niveau de la logique métier, un abus ou une fuite au niveau de la clé, et l’épuisement du solde au niveau du compte. Le point API4 « Unrestricted Resource Consumption » de l’OWASP API Security Top 10 (2023) traite du même type de problème : une interface sans limite de consommation de ressources présente des risques pour le service comme pour les coûts. Pour les interfaces d’IA, le risque de coût est souvent plus direct.
2.1 Première ligne budgétaire : budget des utilisateurs et du pool d’essai côté backend applicatif
C’est la seule couche qui permet de faire du « contrôle d’admission ». Elle doit gérer deux niveaux :
- Budget par utilisateur : quota total ou quota journalier de chaque utilisateur en essai. Le quota journalier est réinitialisé par la tâche planifiée de l’application, sans dépendre de la passerelle.
- Budget du pool d’essai : plafond total partagé par tous les utilisateurs en essai. Même si aucun utilisateur ne dépasse sa limite, le coût total doit être plafonné lorsque le nombre d’utilisateurs explose.
Une requête doit obtenir à la fois la réservation au niveau utilisateur et celle au niveau du pool pour passer, et les deux doivent être réalisées dans la même opération atomique ou la même transaction. Sinon, on retrouve une situation de course où « la réservation utilisateur réussit alors que le pool est déjà plein ».
Cette couche doit aussi décider de la taille de la requête côté serveur : quel modèle est autorisé, quelle est la limite de max_tokens, quelle longueur d’entrée ne doit pas être dépassée. Ces paramètres ne doivent pas être transmis tels quels depuis le frontend : il suffirait qu’un utilisateur modifie un paramètre pour que l’estimation du montant devienne fausse.
2.2 Deuxième ligne budgétaire : clé d’essai dédiée, quota et liste blanche de modèles
Côté passerelle, on émet une clé dédiée au trafic d’essai, totalement isolée du trafic de production. Le rôle de cette clé est de limiter la surface d’exposition : si le registre de l’application a un bug ou si la clé fuite, les pertes restent dans la limite du quota de cette clé et n’affectent pas l’activité de production.
Points à respecter lors de la configuration :
- Définir le quota selon « budget du pool d’essai + une marge ». Il doit être légèrement supérieur au budget du pool côté application pour servir de filet de sécurité. Ne pas le fixer à la même valeur que le budget du pool, sinon la réservation applicative ne sert à rien.
- La liste blanche de modèles ne doit contenir que les modèles ouverts à l’essai. Elle empêche d’utiliser la clé d’essai pour appeler des modèles coûteux, mais ne limite ni le nombre d’appels ni la taille ; les limites de taille côté serveur de la section 2.1 restent donc indispensables.
- Le quota étant un plafond souple, cette ligne autorise un « léger dépassement ». Son intérêt est de contenir l’ampleur du dépassement dans une plage acceptable ; il ne faut pas attendre d’elle un zéro dépassement.
La méthode générale consistant à séparer clés, quotas et journaux par projet relève d’un autre sujet. Ici, on insiste sur un point : une clé dédiée au trafic d’essai.
2.3 Troisième ligne budgétaire : alerte sur le solde du compte
La documentation d’alerte de solde d’APIYI précise clairement que l’alerte est une notification et ne bloque pas les requêtes. Lorsque le solde passe sous le seuil, l’alerte envoie le message au responsable, qui décide de recharger, de suspendre l’entrée d’essai ou d’enquêter sur le trafic anormal.
Deux conseils pour cette couche :
- Fixer le seuil d’alerte en fonction de « la consommation maximale pendant le délai entre détection et traitement », pas un entier au hasard.
- Associer l’alerte à une action de traitement précise, par exemple écrire dans le manuel d’astreinte : « après réception de l’alerte, fermer d’abord l’entrée d’inscription à l’essai ». Une alerte sans action de suivi ne sert à rien.
3 Un registre de concurrence hypothétique : de la réservation atomique à la réconciliation
Cette section présente une conception illustrative. La structure des tables, les prix et les chiffres sont hypothétiques : ils servent à expliquer le flux et ne correspondent à aucune donnée réellement mesurée sur un système. Le flux comporte cinq étapes :
Vérification atomique et réservation → le serveur verrouille le model et l'échelle → envoi de la requête
→ règlement / traitement de l'échec → correction hors ligne par réconciliation

3.1 Structure des tables et états du registre de budgets
La structure de données illustrative repose sur deux tables : budgets enregistre la limite, le montant déjà dépensé et le montant réservé pour chaque utilisateur et pour le pool d’essai ; reservations enregistre chaque réservation et son état.
| État de la réservation | Signification | Impact sur la « marge disponible » |
|---|---|---|
| reserved | Réservé, requête en cours | Occupe le montant estimé |
| settled | Usage réel obtenu, règlement effectué | Converti en dépensé, libère la différence |
| released | Requête confirmée comme non exécutée | Libération totale |
| unknown | Timeout, déconnexion, coût inconnu | Reste occupé, en attente de réconciliation |
La marge disponible se calcule ainsi : limit - spent - reserved, où reserved inclut les réservations en état unknown.
3.2 Vérification et réservation atomiques : empêcher deux requêtes concurrentes de passer en même temps
L’astuce consiste à fusionner la « vérification » et la « réservation » en une seule instruction de mise à jour conditionnelle, en laissant la base de données garantir l’atomicité :
-- Illustration : ne réserver que si le solde restant est suffisant, renvoie le nombre de lignes affectées
UPDATE budgets
SET reserved = reserved + :estimate
WHERE owner_id IN (:user_id, :pool_id)
AND limit_amount - spent - reserved >= :estimate;
-- Le nombre de lignes affectées doit être égal à 2 (utilisateur et pool tous deux réussis), sinon on annule la transaction et on rejette la requête
Le montant estimé doit prendre la valeur maximale : le nombre de tokens d’entrée multiplié par le prix unitaire d’entrée, plus max_tokens multiplié par le prix unitaire de sortie. La consommation réelle est généralement inférieure à ce chiffre, il suffit de rembourser la différence lors du règlement. Mieux vaut réserver un peu trop que pas assez.
3.3 Verrouillage côté serveur du modèle et de la taille de la tâche
Les paramètres d’estimation utilisés pour la réservation doivent être strictement identiques à ceux de la requête réellement envoyée. Voici un exemple de code :
ALLOWED_TRIAL_MODELS = {"trial-model-a"} # Illustration : modèles ouverts aux essais
MAX_OUTPUT_TOKENS = 1024 # Illustration : plafond imposé par le serveur
MAX_INPUT_TOKENS = 8000
def build_trial_request(user_input, requested_model):
model = requested_model if requested_model in ALLOWED_TRIAL_MODELS \
else "trial-model-a"
input_tokens = count_tokens(user_input)
if input_tokens > MAX_INPUT_TOKENS:
raise InputTooLarge()
estimate = price_in(model) * input_tokens \
+ price_out(model) * MAX_OUTPUT_TOKENS
return model, MAX_OUTPUT_TOKENS, estimate
Le max_tokens et le modèle transmis par le front-end ne sont que des valeurs indicatives : c’est en dernier ressort la décision du serveur qui fait foi.
3.4 Envoi des requêtes, règlement et traitement des échecs
Avant d’envoyer la requête, générez un identifiant de requête unique et consignez-le dans l’enregistrement de réservation, histoire de pouvoir le retrouver ensuite dans les logs. Une fois la réponse revenue, trois cas de figure :
- Succès avec
usagedisponible : on calcule le montant à partir de la consommation réelle,spent += actual,reserved -= estimate, et la réservation passe au statut settled. - Échec clairement non exécuté : par exemple une erreur de validation des paramètres ou d’authentification, bref une erreur qui garantit que la requête n’a pas été facturée. On libère alors la réservation, statut released.
- Timeout ou connexion interrompue : la requête a peut-être déjà été exécutée en amont et facturée, simplement le résultat n’est pas revenu. Dans ce cas, il ne faut pas compter le coût comme zéro : statut unknown, et la réservation reste immobilisée.
C’est le troisième cas qui pose le plus de problèmes. Libérer la réservation dès qu’il y a un timeout revient à effacer du registre des coûts qui ont peut-être bien été engagés. Et sur les périodes de forte concurrence avec un taux de timeout élevé, ce biais s’accumule sans fin.
3.5 Rapprochement hors ligne : corriger les unknown et les écarts d’estimation
La recherche de logs d’APIYI permet un export incrémental. La documentation la destine au rapprochement hors ligne : on ne peut pas s’en servir pour autoriser chaque requête une par une. Le rapprochement doit donc tourner en tâche planifiée :
- Récupérer les logs incrémentaux depuis le dernier rapprochement, puis les apparier à la table
reservationsvia l’identifiant de requête ou une fenêtre temporelle. - Les réservations unknown qu’on retrouve dans les logs passent en settled avec le montant réel qui y figure ; celles qu’on ne retrouve toujours pas au-delà de la fenêtre convenée passent en released.
- Suivre la distribution des écarts entre montant estimé et montant réel. Si le réel s’approche souvent de l’estimation, voire la dépasse, il faut revenir sur la formule du 3.3.
Le résultat du rapprochement alimente aussi la troisième ligne budgétaire : si le total du registre et la consommation effective du compte ne cessent de diverger, c’est en soi un signal qui mérite un examen manuel.

4 Vérification de la mise en service des lignes budgétaires et message convivial en cas de quota insuffisant
4.1 Liste de contrôle de mise en service des trois lignes budgétaires
| Élément de contrôle | Ligne budgétaire concernée | Méthode de validation |
|---|---|---|
| La réservation de l’utilisateur et celle du pool sont réalisées dans la même transaction | Première ligne | Tester en charge avec des requêtes concurrentes et vérifier que le montant dépensé plus les réservations ne dépasse pas la limite |
model, max_tokens et la longueur d’entrée sont déterminés par le serveur |
Première ligne | Falsifier les paramètres côté frontend et vérifier qu’ils sont sans effet |
Les requêtes en timeout sont marquées unknown et conservent leur réservation |
Première ligne | Injecter une panne de type timeout et vérifier l’état du registre |
La tâche de rapprochement s’exécute périodiquement et traite les unknown |
Première ligne | Vérifier les journaux de rapprochement et les transitions d’état |
| La clé d’essai est indépendante et son quota est légèrement supérieur au budget du pool | Deuxième ligne | Vérifier la configuration de la clé et la valeur du budget du pool |
| La liste blanche de modèles de la clé d’essai ne contient que les modèles d’essai | Deuxième ligne | Effectuer un appel avec un modèle hors liste blanche et vérifier le rejet |
| Le script de réinitialisation du quota journalier existe et est surveillé | Première et deuxième lignes | Vérifier l’historique d’exécution de la tâche planifiée |
| Le seuil d’alerte de solde correspond au manuel de traitement | Troisième ligne | Simuler le processus depuis l’alerte jusqu’à la fermeture de l’accès |
4.2 Message affiché à l’utilisateur en cas de quota insuffisant
En cas d’échec de la réservation, l’application doit renvoyer une erreur métier explicite, plutôt que de laisser la requête atteindre la passerelle puis de renvoyer une erreur difficile à comprendre. Le message devrait contenir trois informations :
- Ce qui s’est passé : par exemple « le quota d’essai du jour est épuisé » ou « les places d’essai actuelles sont complètes ». Il faut distinguer le quota insuffisant de l’utilisateur et le pool d’essai complet.
- Quand cela sera rétabli : si un quota journalier est défini, indiquer l’heure de réinitialisation ; si le quota ponctuel est épuisé, expliquer les options de mise à niveau disponibles par la suite.
- L’état actuel : vous pouvez afficher le quota restant, mais en vous basant sur le solde disponible du registre et en déduisant les réservations en cours, pour éviter le cas « un solde est affiché mais la requête est refusée ».
Après avoir effectué ces contrôles, une méthode simple permet de valider l’ensemble des lignes budgétaires : simuler un pic de concurrence combiné à un timeout en amont, puis confirmer que, dans le registre, « dépensé + réservations en cours » n’est jamais inférieur à la consommation réelle après rapprochement, et que la consommation de la clé d’essai ne dépasse pas significativement son quota. Si ces deux conditions sont remplies, les trois lignes budgétaires sont réellement opérationnelles.
Références
- Documentation APIYI sur la gestion des jetons : limites souples,
remain_quota, réinitialisation quotidienne et liste blanche de modèles- Lien :
docs.apiyi.com/api-capabilities/token-management
- Lien :
- Documentation APIYI sur les quotas pré-débités : mécanisme d’estimation pré-débitée et de règlement a posteriori
- Lien :
docs.apiyi.com/faq/pre-deduction-quota
- Lien :
- Documentation APIYI sur les alertes de solde : l’alerte ne fait que notifier, elle ne bloque pas
- Lien :
docs.apiyi.com/faq/balance-alerts
- Lien :
- Documentation APIYI sur la consultation des journaux : export incrémental et rapprochement hors ligne
- Lien :
docs.apiyi.com/api-capabilities/log-query
- Lien :
- OWASP API Security Top 10 2023 : API4 Unrestricted Resource Consumption
- Lien :
api-security.owasp.org/editions/2023/en/0xa4-unrestricted-resource-consumption/
- Lien :
« Toute action se prépare pour réussir ; sans préparation, elle échoue. » — Lijing · Zhongyong
