Skip to content

Limites de taxa · Developers

Como a API pública do Dailybot regula os chamadores, como você descobre que foi throttled e como projetar uma integração que fica abaixo da linha.

Os rate limits são aplicados **por credencial** (por chave de API ou por sessão Bearer da CLI), **por escopo nomeado**, **por hora**. Escopos nomeados agrupam endpoints que compartilham um orçamento — um burst de send-message, por exemplo, não consome do orçamento de leituras de usuários.

O que acontece quando você bate um limite

Quando o orçamento horário de um escopo é esgotado, a API retorna 429 Too Many Requests com um header Retry-After (segundos até o reset) e um pequeno body JSON. Cada tipo de resposta 4xx e 5xx está catalogado em /pt/developers/errors.

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."
}

Escopos nomeados

A API pública agrupa endpoints em um pequeno conjunto de escopos nomeados para que um burst em uma atividade não bloqueie atividade não relacionada da mesma credencial. A lista atual descreve a família de endpoints que cobre:

  • leituras default — Todo endpoint GET não coberto por um escopo mais específico abaixo. A maioria das integrações de leitura vive aqui.
  • escritas gerais — POST/PATCH/DELETE não-agente, não-mensageria — users, teams, kudos, invitations, workflows, forms, check-ins.
  • mensageria — Cada endpoint que envia uma mensagem do bot em uma plataforma de chat (Slack, Teams, Discord, Google Chat) ou abre uma conversa.
  • e-mail — Cada endpoint que envia e-mail transacional em nome do chamador.
  • convites — Cada endpoint que cria ou reenvia um convite de usuário ou guest.
  • trigger de workflows — Execuções de workflow disparadas por API.
  • escopo de agente — Os endpoints do sistema de agentes (reports, health, messages, email, webhook, register) — projetados para chamadores máquina de maior cadência.
  • autenticação — Endpoints de OTP + OAuth + token-exchange. Mais estritos, para proteger a superfície de auth contra brute-force.

Cotas atuais por escopo

As cotas concretas por escopo não são publicadas como contrato. Se você precisa projetar capacidade contra um número específico, contate o suporte do Dailybot — compartilharemos o valor atual para os escopos da sua conta. No caso geral, o guia de projeto abaixo mantém toda integração bem-portada muito abaixo da linha sem precisar de um spec.

Guia de projeto

  • Faça cache de respostas de leitura quando o dado é do org e não muda muito — info da organização, lista de usuários, lista de equipes.
  • Use cursores de paginação — não reescaneie uma lista do offset 0 em cada rodada.
  • Faça batch das escritas (um POST com 20 itens em vez de 20 POSTs) quando o endpoint suportar.
  • Honre Retry-After em cada 429 — não faça retry antes. Adicione jitter ao seu delay de retry para evitar resets em manada quando a janela de cota vira.
  • Para heartbeats de cadência de agente (agent-health, agent-messages), escolha um intervalo que combine com sua necessidade real de poll. Um heartbeat a cada 5 segundos é quase sempre over-engineering.