Passer au contenu principal
Lisez le code d’erreur et le reason d’un 429 pour savoir quelle limite a arrêté la requête, puis attendez Retry-After ou modifiez la limite. Le routage et les fallbacks réduisent les échecs des fournisseurs, mais une requête peut toujours être limitée par un fournisseur ou par une politique de l’espace de travail ou de la clé. Tous renvoient 429. Si l’application des quotas de la passerelle est brièvement indisponible, la passerelle renvoie 503 avec des indications pour réessayer.

Limites de la passerelle

Chaque utilisateur de chaque espace de travail dispose d’un quota de requêtes par minute, mesuré sur une minute glissante. Les clés API créées par un même utilisateur le partagent. Les requêtes OAuth sont comptées pour l’utilisateur connecté, et les clés sans propriétaire partagent un quota unique de l’espace de travail. Le quota augmente automatiquement à mesure que l’espace de travail s’établit. Un espace de travail obtient la ligne la plus élevée à laquelle il a droit, et les changements prennent effet en quelques minutes : Les modèles gratuits disposent aussi par défaut d’un quota de 1 500 requêtes par jour UTC. Il est partagé entre tous les modèles gratuits et entre tous les espaces de travail dans lesquels le même utilisateur envoie des requêtes. Les requêtes vers des modèles payants ne l’utilisent pas. Une requête gratuite admise compte même si le fournisseur échoue ensuite, et les fallbacks de fournisseurs au sein d’une même requête comptent une seule fois. Les deux limites s’appliquent à toutes les régions de la passerelle et peuvent être relevées pour un utilisateur et un espace de travail donnés. Les opérations sur les fichiers et l’interrogation de l’état des tâches utilisent le quota par minute ; les endpoints de gestion ne l’utilisent pas. Une requête refusée renvoie 429 avec Retry-After en secondes. Attendez ce délai avant de réessayer.

Limites de l’API de gestion

Les endpoints de gestion, comme /v1/keys, /v1/logs et /v1/analytics, partagent un quota de 200 unités par minute pour chaque identifiant. Chaque clé de gestion, jeton OAuth et session du tableau de bord a son propre quota, et les requêtes sans identifiant en partagent un par adresse IP. Les endpoints de modèles, de fichiers, de lots et de tâches ne l’utilisent pas. Chaque requête consomme des unités selon la quantité de travail qu’elle demande : /v1/health et les requêtes CORS de pré-vérification sont gratuites. Une requête au-delà du quota renvoie 429 avec rate_limit_exceeded, le motif management_api_rate_limit et Retry-After: 60. Le décompte est approximatif et ces réponses ne contiennent pas d’en-têtes x-ratelimit-* : étalez donc vos scripts de masse plutôt que de les pousser jusqu’à la limite.

Limites de clés et budgets

Les limites quotidiennes, hebdomadaires ou mensuelles de requêtes et de dépenses d’une clé API, ainsi que les budgets de l’espace de travail, renvoient 429 avec key_limit_exceeded une fois atteints. Les champs reason, limit_window et reset_at du corps indiquent de quelle limite il s’agit et quand sa fenêtre se réinitialise, et Retry-After donne le nombre de secondes d’ici là. Retry-After est absent lorsque la limite ne se réinitialise pas seule, comme un budget sur toute la durée ou une clé bloquée de manière souple. Ne réessayez pas : relevez le budget de l’espace de travail, relevez la limite de la clé ou utilisez une autre clé. Les propriétaires et administrateurs de l’espace de travail gèrent les budgets avec une clé de gestion via /v1/budgets ou dans Paramètres → Budgets, qui affiche pour chaque budget les dépenses à ce jour, la part utilisée, une projection pour la période et le moment de la réinitialisation. Les budgets quotidiens, hebdomadaires et mensuels se réinitialisent sur des limites UTC : minuit, le lundi à 00:00 et le 1er du mois. Les alertes de dépenses peuvent prévenir avant que ces limites soient atteintes. Une règle de dépenses réglée sur le blocage renvoie 429 avec spend_rule_blocked. Elle fonctionne au mieux et démarre quelques minutes après le dépassement de sa limite : utilisez donc les limites de clés et les budgets pour des plafonds exacts. Un en-tête x-phaseo-spend-warning signifie qu’un blocage peut suivre.

Budgets de département

Les propriétaires et administrateurs gèrent les budgets de département avec phaseo department-budgets, l’API /v1/department-budgets, dans Paramètres → Budgets, ou avec la ressource phaseo_department_budget du fournisseur Terraform. Les dépenses d’un département comptent les mêmes clés et requêtes OAuth que les limites de débit des départements. Une fois qu’un département a utilisé son budget quotidien, hebdomadaire ou mensuel, les requêtes par clé API qui comptent pour lui renvoient 429 avec key_limit_exceeded et le motif department_daily_cost_budget_reached, department_weekly_cost_budget_reached ou department_monthly_cost_budget_reached. Les champs department_id et department_name du corps identifient le département, et reset_at et Retry-After indiquent quand son budget se réinitialise.
  • Si la vérification du budget est brièvement indisponible, les requêtes sont autorisées : un département peut donc dépasser son budget pendant un court instant.
  • Les propriétaires et administrateurs reçoivent une notification push mobile vers 80 % puis à 100 % d’un budget. Pour ces alertes, les budgets sont vérifiés toutes les 15 minutes : des requêtes peuvent donc être refusées avant l’arrivée de l’alerte à 100 %.

Politiques de limite de débit

Les administrateurs de l’espace de travail peuvent créer des politiques nommées qui définissent requests_per_minute, tokens_per_minute et concurrent_requests, et les affecter à des clés, des membres, des départements ou des utilisateurs finaux. Gérez-les avec phaseo rate-limits policies et phaseo rate-limits assignments, l’API /v1/rate-limits, dans Paramètres → Limites de débit, ou avec les ressources phaseo_rate_limit_policy et phaseo_rate_limit_assignment du fournisseur Terraform. Ce qui compte pour un département. Une clé liée à un département ne compte que pour ce département. Toute autre clé compte pour tous les départements auxquels appartient la personne qui l’a créée, et les requêtes OAuth comptent pour tous les départements de leur utilisateur. Un membre avec un département de remplacement ne compte que pour ce département. Pour que ces clés et requêtes OAuth ne comptent que pour le département principal de la personne, réglez l’attribution par département sur primary dans Paramètres → Notifications, ou avec spend.department_attribution dans PATCH /v1/notifications/settings et une clé de gestion. Les budgets de département et les règles de dépenses utilisent le même réglage. Lorsque plusieurs politiques s’appliquent, chacune est comptée et la première épuisée refuse la requête. Les politiques s’ajoutent aux limites de la passerelle. Les modifications de politiques prennent effet en une minute environ ; les changements d’appartenance à un département effectués dans le tableau de bord ou via SCIM peuvent prendre jusqu’à cinq minutes environ.

Requêtes et tokens par minute

Les deux sont mesurés sur une minute glissante. tokens_per_minute compte les tokens d’entrée et de sortie de chaque requête une fois celle-ci terminée, y compris les requêtes en streaming et les requêtes en échec qui ont consommé des tokens. Une requête est refusée dès que l’utilisation sur la dernière minute atteint la limite : les requêtes déjà en cours peuvent donc la faire dépasser. Les fallbacks de fournisseurs au sein d’une même requête comptent une seule fois. Une requête refusée renvoie 429 avec rate_limit_exceeded, le motif policy_requests_per_minute ou policy_tokens_per_minute, le policy_id, le limit_scope (key, member, department, workspace ou end_user) et Retry-After en secondes. Les réponses aux requêtes couvertes par une politique portent les en-têtes de la limite la plus restrictive : Une requête refusée ne porte que les en-têtes de la limite qui l’a refusée. Le comptage se fait en arrière-plan : remaining est donc approximatif, et les en-têtes de tokens n’incluent pas encore l’utilisation de la requête en cours.

Requêtes simultanées

concurrent_requests plafonne le nombre de requêtes en cours en même temps. Une requête occupe un emplacement depuis son admission jusqu’à l’envoi complet de sa réponse, y compris l’intégralité d’une réponse en streaming ; les fallbacks de fournisseurs et de modèles au sein de la requête partagent cet emplacement. Lorsque tous les emplacements sont occupés, la requête est refusée avec le motif policy_concurrent_requests et Retry-After: 1. La vérification d’une limite de simultanéité attend le compteur de la politique, ce qui ajoute un peu de latence. Un emplacement dont la libération est perdue se libère seul au bout de 15 minutes. Les lots et les sessions en temps réel ne sont pas limités, et une génération vidéo n’occupe un emplacement que pendant la requête qui la lance.

Politiques strictes

Par défaut, une politique est permissive en cas d’échec : si ses limites ne peuvent pas être vérifiées, la requête est autorisée. Définissez fail_closed pour la rendre stricte. Une politique stricte vérifie les limites de requêtes et de tokens avant l’envoi de la requête plutôt qu’en arrière-plan, ce qui les rend exactes mais ajoute de la latence. Si elles ne peuvent pas être vérifiées en deux secondes, la requête est refusée avec le motif policy_unavailable. Les refus pour simultanéité et policy_unavailable ne portent aucun en-tête x-ratelimit-*.

Limites des fournisseurs

Les requêtes BYOK utilisent les limites de votre compte chez le fournisseur. Les requêtes gérées utilisent la capacité partagée des fournisseurs, qui n’est pas un quota propre à votre espace de travail. Phaseo transmet un Retry-After validé lorsque le fournisseur en envoie un. Les réponses BYOK peuvent aussi contenir des en-têtes X-Phaseo-Upstream-RateLimit-* ; les requêtes gérées les omettent, car ils décrivent une capacité partagée. Les autres en-têtes du fournisseur ne sont pas transmis. Consultez Codes d’erreur pour les codes 429 des fournisseurs.

Gérer une requête limitée

  1. Lisez le code d’erreur pour distinguer une limitation temporaire d’une limite, d’un budget ou d’une politique qui nécessite un changement de configuration.
  2. Respectez Retry-After lorsqu’il est présent. Il peut s’agir de secondes ou d’une date HTTP ; validez-le avant de planifier une nouvelle tentative.
  3. Sinon, utilisez un backoff exponentiel avec gigue et un délai maximal.
  4. Bornez les nouvelles tentatives par un nombre d’essais et une échéance globale. Annulez le travail abandonné et libérez le corps de chaque réponse en échec avant de réessayer.
  5. Réduisez la simultanéité si la limitation persiste.
Ne réessayez pas automatiquement une soumission de tâche ambiguë et ne rejouez pas des actions d’outils déjà terminées. Une requête peut avoir atteint le fournisseur même si le client a perdu la réponse : une nouvelle tentative peut donc dupliquer le travail et les frais. Pour une tâche vidéo ou par lots acceptée, utilisez son endpoint d’état au lieu de la soumettre à nouveau. Pour surveiller la limitation, suivez les taux de 429 par endpoint et par modèle, et vérifiez la fréquence des fallbacks dans les journaux de requêtes. Comparez-les à vos paramètres de routage et, pour le trafic BYOK, aux quotas de votre compte chez le fournisseur. Les garde-fous déterminent quelles clés peuvent utiliser quels modèles et fournisseurs.
Dernière modification le 13 novembre 2026