Limites de débit de l'API et meilleures pratiques

Chaque clé API Ody reçoit 600 requêtes par minute sur /v1/api/* et le point de terminaison MCP — lisez les en-têtes RateLimit-* sur chaque réponse, et reculez avec la valeur Retry-After lorsque vous recevez un 429.

Comment fonctionne la limite

• La limite est par clé, comptée dans une fenêtre fixe de 60 secondes. Les requêtes sans clé valide sont limitées par IP à la place.
• Chaque réponse — succès ou erreur — contient trois en-têtes standard :
  • RateLimit-Limit — votre budget par minute (600).
  • RateLimit-Remaining — requêtes restantes dans la fenêtre actuelle.
  • RateLimit-Reset — secondes avant la réinitialisation de la fenêtre.
• Dépasser la limite renvoie 429 avec le code d'erreur resource_exhausted et un en-tête Retry-After (secondes). Attendez au moins ce délai avant de réessayer.

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 600
RateLimit-Remaining: 0
RateLimit-Reset: 23
Retry-After: 23

Rester sous la limite

• Surveillez RateLimit-Remaining et ralentissez de manière proactive à mesure qu'il approche de zéro, plutôt que de réagir aux 429.
• Utilisez des webhooks au lieu du polling. Abonnez un point de terminaison à des événements comme message.received et Ody vous enverra l'activité — voir Recevoir des webhooks et vérifier les signatures. Si vous devez interroger, toutes les 10 à 30 secondes suffisent amplement pour une boîte de réception partagée.
• Réessayez avec un backoff exponentiel et un jitter sur 429 et 5xx, en plafonnant les tentatives. Respectez Retry-After lorsqu'il est présent. Pour les envois, associez les tentatives à une Idempotency-Key afin d'éviter les doubles envois — voir Pagination, idempotence et gestion des erreurs.
• Demandez des pages plus grandes (?limit= jusqu'au maximum de chaque point de terminaison) au lieu de nombreuses petites pages lors de la synchronisation des données.

Meilleures pratiques de sécurité des clés

• Limitez la portée de chaque clé au minimum nécessaire. Désélectionnez les portées lors de la création — un tableau de bord qui ne fait que lire les conversations ne devrait avoir que conversations:read. Voir Obtenir votre clé API Ody.
• Utilisez des clés de test partout où de vrais SMS seraient un bug. Les environnements de développement et l'intégration continue (CI) devraient fonctionner avec des clés ody_test_… afin que les envois de messages soient simulés — voir Développer en toute sécurité avec le mode test.
• Une clé par intégration. Des clés séparées pour Zapier, votre serveur et un assistant IA signifient que vous pouvez en révoquer une sans casser les autres, et la colonne "dernière utilisation" dans Paramètres → API Développeur reste pertinente.
• Gardez les clés côté serveur. N'incorporez jamais une clé dans les applications mobiles, le JavaScript du navigateur ou les documents partagés — toute personne disposant de la clé peut agir en tant que son créateur dans les limites de ses portées.
• Faites pivoter et élaguez. Révoquez les clés que vous n'utilisez plus. Étant donné que le texte en clair n'est affiché qu'une seule fois, la rotation signifie créer une nouvelle clé, la déployer, puis révoquer l'ancienne.

Articles connexes

• Présentation de l'API et authentification
• Pagination, idempotence et gestion des erreurs
• Recevoir des webhooks et vérifier les signatures
• Développer en toute sécurité avec le mode test