Skip to content

Límites de tasa · Developers

Cómo la API pública de Dailybot regula a los llamantes, cómo sabes que has sido throttled y cómo diseñar una integración que se mantenga por debajo.

Los rate limits se aplican **por credencial** (por API key o por sesión Bearer del CLI), **por scope nombrado**, **por hora**. Los scopes nombrados agrupan endpoints que comparten un presupuesto — un burst de send-message, por ejemplo, no consume del presupuesto de lecturas de usuarios.

Qué pasa cuando alcanzas un límite

Cuando el presupuesto horario de un scope se agota, la API devuelve 429 Too Many Requests con un header Retry-After (segundos hasta el reset) y un pequeño body JSON. Cada tipo de respuesta 4xx y 5xx está catalogado en /es/developers/errors.

Ejemplo de respuesta 429

HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{
  "detail": "Request was throttled. Expected available in 30 seconds."
}

Scopes nombrados

La API pública agrupa endpoints en un pequeño conjunto de scopes nombrados para que un burst en una actividad no bloquee actividad no relacionada de la misma credencial. La lista actual describe la familia de endpoints que cubre:

  • lecturas default — Todo endpoint GET no cubierto por un scope más específico abajo. La mayoría de integraciones de lectura viven aquí.
  • escrituras generales — POST/PATCH/DELETE no-agente, no-mensajería — users, teams, kudos, invitations, workflows, forms, check-ins.
  • mensajería — Cada endpoint que envía un mensaje del bot en una plataforma de chat (Slack, Teams, Discord, Google Chat) o abre una conversación.
  • email — Cada endpoint que envía correo transaccional en nombre del llamante.
  • invitaciones — Cada endpoint que crea o reenvía una invitación de usuario o guest.
  • trigger de workflows — Corridas de workflow disparadas por API.
  • con scope de agente — Los endpoints del sistema de agentes (reports, health, messages, email, webhook, register) — diseñados para llamantes máquina de mayor cadencia.
  • autenticación — Endpoints de OTP + OAuth + token-exchange. Más estrictos, para proteger la superficie de auth contra brute-force.

Cuotas actuales por scope

Las cuotas concretas por scope no se publican como contrato. Si necesitas diseñar capacidad contra un número específico, contacta a soporte de Dailybot — compartiremos el valor actual para los scopes de tu cuenta. En el caso general, la guía de diseño de abajo mantiene toda integración bien portada muy por debajo de la línea sin necesidad de un spec.

Guía de diseño

  • Cachea respuestas de lectura cuando el dato es del org y no cambia seguido — info de organización, lista de usuarios, lista de equipos.
  • Usa cursores de paginación — no reescanees una lista desde offset 0 en cada corrida.
  • Bátchea escrituras (un POST con 20 ítems en vez de 20 POSTs) cuando el endpoint lo soporte.
  • Honra Retry-After en cada 429 — no reintentes antes. Agrega jitter a tu delay de reintento para evitar resets en manada cuando la ventana de cuota da la vuelta.
  • Para heartbeats de cadencia de agente (agent-health, agent-messages), elige un intervalo que combine con tu necesidad real de poll. Un heartbeat cada 5 segundos es casi siempre over-engineering.