Rate Limits · Developers

Los rate limits se aplican por credencial (por API key o por sesión CLI-Bearer), por scope nombrado, por hora. Los scopes nombrados agrupan endpoints que comparten un presupuesto — una ráfaga de llamadas a send-message, por ejemplo, no consume del presupuesto para llamadas de lectura de usuarios.

Qué pasa cuando alcanzas un límite

Cuando el presupuesto horario de un scope se agota, la API retorna 429 Too Many Requests con un header Retry-After (segundos hasta el reinicio) y un cuerpo JSON.

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.",
  "code": "free_plan_daily_limit_exceeded"
}

El valor de Retry-After es el número de segundos hasta que el límite se reinicia. Siempre respétalo — no reintentes antes.

Throttles diarios del plan gratuito

En organizaciones de plan gratuito, dos endpoints tienen un límite diario estricto por org además de los scopes horarios por credencial. Estos throttles no aplican en planes de pago ni con API key.

Endpoint	Límite (plan gratuito)	Al excederse
POST /v1/agent-reports/	50 por org por día	429 + code: "free_plan_daily_limit_exceeded"
POST /v1/send-email/	20 por org por día	429 + code: "free_plan_daily_limit_exceeded"

• Los límites diarios se reinician a las 00:00 UTC.
• El header Retry-After indica segundos hasta el reinicio diario.
• Los planes de pago no tienen cap diario en estos endpoints.

Scopes nombrados

La API agrupa endpoints en un pequeño conjunto de scopes nombrados para que una ráfaga en una actividad no bloquee actividades no relacionadas. La lista actual de scopes:

• default reads — Todo GET no cubierto por un scope más específico.
• general writes — POST/PATCH/DELETE que no son agent ni messaging — users, teams, kudos, invitations, workflows, forms, check-ins.
• messaging — Todo endpoint que envía mensajes de bot (Slack, Teams, Discord, Google Chat).
• email — Todo endpoint que envía email transaccional.
• invitations — Todo endpoint que crea o reenvía invitaciones.
• workflow triggers — Ejecuciones de workflows vía API.
• agent-scoped — Endpoints del sistema de agentes (reports, health, messages, email, webhook, register).
• authentication — Endpoints de OTP + OAuth + exchange de token. Más estricto para proteger la superficie de auth.

Cuotas por scope

Las cuotas concretas por scope no se publican como contrato. Si necesitas diseñar capacidad contra un número específico, contacta al soporte de Dailybot.

Guía de diseño

• Cachea las respuestas de lectura cuando los datos son de alcance org y no cambian frecuentemente — información de la organización, lista de usuarios, lista de equipos.
• Usa cursores de paginación — no re-escanees una lista desde offset 0 en cada ejecución.
• Agrupa writes (un POST con 20 ítems en lugar de 20 POSTs) cuando un endpoint lo soporte.
• Respeta Retry-After en cada 429 — no reintentes antes. Añade jitter para evitar thundering-herd.
• Para heartbeats de agentes (agent-health, agent-messages), elige un intervalo que coincida con tu necesidad real. Un heartbeat cada 5 segundos casi siempre es sobredimensionado.