Erreurs et limites de débit

Chaque point de terminaison échoue de la même manière, donc un client gère les erreurs, les limites de débit et les nouvelles tentatives une seule fois et réutilise ce code partout, y compris via MCP.

Chaque réponse non-2xx est un objet JSON unique :

{
  "defined": false,
  "code": "TOO_MANY_REQUESTS",
  "message": "Too many requests",
  "data": { "reason": "rate_limit.exceeded", "retryAfterMs": 12000 }
}

• code est l'erreur au niveau HTTP, par exemple UNAUTHORIZED, FORBIDDEN, NOT_FOUND, BAD_REQUEST ou TOO_MANY_REQUESTS.
• data.reason, lorsqu'il est présent, est une raison plus précise lisible par machine, comme auth.key_not_found ou rate_limit.exceeded. Effectuez une branche sur celui-ci plutôt que sur message, qui est destiné aux utilisateurs et peut changer.
• defined est true lorsque l'opération répertorie cette erreur dans la référence de l'API, et false pour les erreurs que toute requête peut rencontrer (authentification, limites de débit, une route inconnue).
• Un échec de validation répond BAD_REQUEST avec les problèmes dans data.formErrors et data.fieldErrors.

Chaque réponse comporte également un X-Request-ID. Citez-le lorsque vous contactez le support, et nous pourrons retrouver cette requête exacte.

Chaque réponse indique la limite contre laquelle elle a été comptabilisée, sous deux formes :

• les en-têtes X-RateLimit-* ;
• les champs structurés IETF RateLimit (état en direct : r est le nombre de requêtes restantes, t le nombre de secondes avant la réinitialisation de la fenêtre) et RateLimit-Policy (le quota : q est la limite, w la fenêtre en secondes).

Une réponse 429 comporte également Retry-After en secondes et data.retryAfterMs. Attendez au moins ce délai avant la requête suivante ; une nouvelle tentative plus tôt est comptabilisée et refusée à nouveau.

Une opération d'écriture qui répertorie un en-tête Idempotency-Key dans la référence de l'API peut être réessayée sans effectuer le travail deux fois. Envoyez une clé par écriture logique et répétez la même clé à chaque nouvelle tentative :

• la même clé avec le même corps dans les 24 heures rejoue la réponse stockée ;
• la même clé avec un corps différent est refusée avec 422 ;
• un doublon qui arrive alors que la première tentative est toujours en cours reçoit 409.

Une opération sans cet en-tête n'est pas idempotente, donc ne la réessayez que lorsque vous savez que la première tentative n'a pas abouti.