Erreurs et limites de débit

Codes de statut

Le 403 passe avant le 404. Quand l'URL nomme une organisation ou une boutique, la route vérifie d'abord votre accès : une requête vers un tenant que vous ne pouvez pas atteindre renvoie 403, que la ressource existe ou non. Dans un tenant qui vous est accessible, les recherches sont limitées à ce tenant : un identifiant qui appartient à quelqu'un d'autre renvoie 404, exactement comme un identifiant qui n'existe pas. Quelques routes nomment une ressource par son propre identifiant (/api/tasks/[id]/stream, par exemple) : elles la chargent, puis vérifient le tenant auquel elle appartient. Elles renvoient donc 404 quand rien ne porte cet identifiant, et 403 quand la ressource vit dans un tenant qui ne vous est pas accessible. Dans tous les cas, un 404 sur un appel authentifié veut dire une seule chose : aucune ressource ne porte cet identifiant dans un tenant qui vous est accessible.

Le 403 couvre aussi deux cas que le corps de la réponse distingue : aucun accès, ou un accès avec un rôle insuffisant. Lisez le champ error plutôt que de déduire à partir du statut.

Un 402 signifie que rien n'a été streamé. Une requête dont le coût estimé dépasse votre solde est refusée avant de s'exécuter (voir Crédits et mesure). Vous ne payez jamais une requête qui allait forcément manquer de crédits. Rechargez ou attendez la réinitialisation : réessayer tout de suite renvoie le même 402.

Limites de débit

Les plafonds s'appliquent par endpoint et par acteur, et non sous la forme d'un chiffre global unique. L'acteur est une adresse IP sur les routes publiques, et l'identifiant ou l'utilisateur sur les routes authentifiées. C'est la raison concrète de détenir une clé Intelligence plutôt que d'appeler en anonyme : depuis une plateforme serverless, votre IP change d'une invocation à l'autre, et un plafond compté par IP devient inutilisable.

Les plafonds eux-mêmes sont opérationnels, pas contractuels : ils sont ajustés sur la charge réelle et peuvent changer. Voyez un 429 comme un signal pour ralentir, jamais comme une valeur à coder en dur.

Que faire face à un 429

Backoff exponentiel avec jitter. Commencez à une seconde, doublez à chaque essai, plafonnez autour d'une minute. Le jitter compte plus que la base : sans lui, tout ce qui a été freiné réessaie au même instant, et vous recréez le pic qui vous a valu la limite.

Ne relancez pas un 402, un 403 ou un 404 : aucune de ces réponses ne changera à force de redemander.

Quand la limitation de débit ne peut pas s'appliquer

Si le stockage derrière le limiteur est injoignable, les gardes ne refusent pas la requête. C'est un choix délibéré, avec un vrai compromis : la panne d'un service de comptage ne doit pas entraîner le produit avec elle. Des garde-fous de dépense refusaient autrefois les requêtes quand le limiteur tombait : c'est pour cette raison que la règle est écrite ici plutôt que laissée implicite.

Erreurs du serveur MCP

Les erreurs des outils MCP reviennent comme des erreurs d'outil, pas comme des échecs HTTP : le transport a réussi, c'est l'outil qui a refusé. Un outil que votre autorisation n'ouvre pas n'est pas enregistré du tout : il est absent de la liste des outils, au lieu d'y figurer et d'échouer. Voir Outils MCP et scopes.