Limites de débit et erreurs

Combien de requêtes l’API et le serveur MCP d’iyedy acceptent par minute, les en-têtes qui vous situent, et chaque code d’erreur avec ce qu’il faut faire.

Les limites se comptent par personne, sur chaque requête à l’API avec un jeton ou une session, et sur les appels MCP. Dans une organisation Team, la limite de l’organisation s’applique aussi aux requêtes de ses membres. Un même schéma accepte jusqu’à 10 écritures par seconde.

Savoir où vous en êtes

Chaque réponse porte deux en-têtes :

• RateLimit-Policy : la limite qui s’applique à vous ;
• RateLimit : ce qui reste dans la fenêtre en cours.

Quand vous la dépassez, la réponse est 429 avec le code rate_limited, le nom de la limite dans detail.bucket, et un en-tête Retry-After en secondes. Attendez ce délai, puis réessayez une fois. Ne réessayez que les requêtes qu’on peut répéter sans risque : les lectures, et les requêtes de création envoyées avec un Idempotency-Key.

Tailles

La forme d’une erreur

Chaque erreur est un objet JSON :

{
  "error": {
    "code": "permission_denied",
    "message": "…",
    "detail": { "reason": "insufficient_scope", "required": "cartouche.propose" },
    "requestId": "req_7f3c2a90-5b1e-4c8d-9a61-0e2b4d6f8a13"
  }
}

Donnez le requestId au support quand vous l’interrogez sur une erreur. Le message s’adresse aux personnes ; votre code doit tester code et detail.reason.

Codes d’erreur

Raisons d’un 401

Raisons d’un 403

Adresse non autorisée

Un jeton de compte de service envoyé depuis une adresse hors de celles permises pour ce compte de service est refusé. La réponse est 401 avec unauthenticated et detail.reason ip_not_allowed, comme les autres refus de jeton ci-dessus. Envoyez la requête depuis une adresse permise. Voir Comptes de service.

Trop de requêtes

La réponse est 429 avec le code rate_limited, le nom de la limite dans detail.bucket et un en-tête Retry-After en secondes. Attendez ce délai, puis réessayez une fois, et seulement une requête qu’on peut répéter sans risque. Voir Savoir où vous en êtes et les limites en haut de cette page.

Erreurs du serveur MCP

L’adresse MCP de Claude répond 401 quand la connexion manque ou a expiré, pour que Claude vous reconnecte, et 403 avec insufficient_scope quand un outil demande une autorisation que vous n’avez pas approuvée. Si la connexion d’iyedy est injoignable, elle répond 503 avec Retry-After: 5. Les refus à l’intérieur d’un outil (pas encore de compte iyedy, MCP coupé pour l’organisation, client non autorisé, authentification unique exigée) reviennent comme une erreur d’outil qui dit quoi faire : voir Dépannage de Claude.