Límites de tasa de API y mejores prácticas

Cada clave API de Ody recibe 600 solicitudes por minuto en /v1/api/* y el punto final MCP — lea los encabezados RateLimit-* en cada respuesta y retroceda con el valor Retry-After cuando reciba un 429.

Cómo funciona el límite

• El límite es por clave, contado en una ventana fija de 60 segundos. Las solicitudes sin una clave válida se limitan por IP en su lugar.
• Cada respuesta — éxito o error — incluye tres encabezados estándar:
  • RateLimit-Limit — su presupuesto por minuto (600).
  • RateLimit-Remaining — solicitudes restantes en la ventana actual.
  • RateLimit-Reset — segundos hasta que la ventana se reinicie.
• Exceder el límite devuelve 429 con el código de error resource_exhausted y un encabezado Retry-After (segundos). Espere al menos ese tiempo antes de reintentar.

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

Mantenerse dentro del límite

• Observe RateLimit-Remaining y reduzca la velocidad de forma proactiva a medida que se acerca a cero, en lugar de reaccionar a los 429.
• Use webhooks en lugar de sondeos. Suscriba un punto final a eventos como message.received y Ody le enviará la actividad — vea Recibir webhooks y verificar firmas. Si debe sondear, cada 10 a 30 segundos es suficiente para una bandeja de entrada compartida.
• Reintente con retroceso exponencial y fluctuación en 429 y 5xx, limitando los reintentos. Respete Retry-After cuando esté presente. Para los envíos, combine los reintentos con una Idempotency-Key para que nada se envíe dos veces — vea Paginación, idempotencia y manejo de errores.
• Solicite páginas más grandes (?limit= hasta el máximo de cada punto final) en lugar de muchas pequeñas al sincronizar datos.

Mejores prácticas de seguridad de claves

• Limite cada clave al mínimo necesario. Deseleccione los alcances al crearla — un panel que solo lee conversaciones debería tener solo conversations:read. Vea Obtener su clave API de Ody.
• Use claves de prueba donde los textos reales serían un error. Los entornos de desarrollo y CI deben ejecutarse con claves ody_test_… para que los envíos de mensajes sean simulados — vea Construir de forma segura con el modo de prueba.
• Una clave por integración. Claves separadas para Zapier, su servidor y un asistente de IA significan que puede revocar una sin romper las otras, y la columna "último uso" en Configuración → API de desarrollador sigue siendo significativa.
• Mantenga las claves en el servidor. Nunca incruste una clave en aplicaciones móviles, JavaScript del navegador o documentos compartidos — cualquiera con la clave puede actuar como su creador dentro de sus alcances.
• Rote y elimine. Revoque las claves que ya no utilice. Dado que el texto sin formato solo se muestra una vez, la rotación significa crear una nueva clave, implementarla y luego revocar la antigua.

Artículos relacionados

• Descripción general de la API y autenticación
• Paginación, idempotencia y manejo de errores
• Recibir webhooks y verificar firmas
• Construir de forma segura con el modo de prueba