Rate Limits · Developers

Os rate limits são aplicados por credencial (por API key ou por sessão CLI-Bearer), por scope nomeado, por hora. Os scopes nomeados agrupam endpoints que compartilham um orçamento — uma rajada de chamadas a send-message, por exemplo, não consome do orçamento para chamadas de leitura de usuários.

O que acontece quando você atinge um limite

Quando o orçamento horário de um scope se esgota, a API retorna 429 Too Many Requests com um header Retry-After (segundos até o reset) e um corpo JSON.

Exemplo de resposta 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"
}

O valor de Retry-After é o número de segundos até o limite ser redefinido. Sempre o respeite — não faça retry antes.

Throttles diários do plano gratuito

Em organizações de plano gratuito, dois endpoints têm um limite diário rígido por org além dos scopes horários por credencial. Esses throttles não se aplicam em planos pagos nem com API key.

Endpoint	Limite (plano gratuito)	Ao exceder
POST /v1/agent-reports/	50 por org por dia	429 + code: "free_plan_daily_limit_exceeded"
POST /v1/send-email/	20 por org por dia	429 + code: "free_plan_daily_limit_exceeded"

• Os limites diários são redefinidos às 00:00 UTC.
• O header Retry-After indica segundos até o reset diário.
• Planos pagos não têm cap diário nesses endpoints.

Scopes nomeados

A API agrupa endpoints em um pequeno conjunto de scopes nomeados para que uma rajada em uma atividade não bloqueie atividades não relacionadas. A lista atual:

• default reads — Todo GET não coberto por um scope mais específico.
• general writes — POST/PATCH/DELETE que não são agent nem messaging — users, teams, kudos, invitations, workflows, forms, check-ins.
• messaging — Todo endpoint que envia mensagens de bot (Slack, Teams, Discord, Google Chat).
• email — Todo endpoint que envia e-mail transacional.
• invitations — Todo endpoint que cria ou reenvia convites.
• workflow triggers — Execuções de workflows via API.
• agent-scoped — Endpoints do sistema de agentes (reports, health, messages, email, webhook, register).
• authentication — Endpoints de OTP + OAuth + exchange de token. Mais restritivo para proteger a superfície de auth.

Cotas por scope

As cotas concretas por scope não são publicadas como contrato. Se você precisar dimensionar capacidade contra um número específico, entre em contato com o suporte do Dailybot.

Guia de design

• Cache respostas de leitura quando os dados são de escopo org e não mudam com frequência — informação da organização, lista de usuários, lista de equipes.
• Use cursores de paginação — não re-escaneie uma lista desde offset 0 em cada execução.
• Agrupe writes (um POST com 20 itens em vez de 20 POSTs) quando um endpoint suportar.
• Respeite Retry-After em cada 429 — não faça retry antes. Adicione jitter para evitar thundering-herd.
• Para heartbeats de agentes (agent-health, agent-messages), escolha um intervalo que corresponda à sua necessidade real. Um heartbeat a cada 5 segundos quase sempre é superdimensionado.