Limites e rate limit
Os limites protegem a plataforma e cada clínica. Leia os cabeçalhos e espere o tempo indicado antes de tentar de novo.
Limite padrão
120 requisições a cada 60 segundos por token. Sem token, a contagem é por endereço IP. O limite vale para todas as rotas, inclusive /health.
Cabeçalhos
X-RateLimit-Limit: 120X-RateLimit-Remaining: 119X-RateLimit-Reset: 60Limit é a cota da janela, Remaining o que resta e Reset os segundos até a janela reiniciar.
Quando o limite estoura
A API responde 429 com Retry-After em segundos. Espere esse tempo; repetir antes só prolonga o bloqueio da janela.
{ "error": { "code": "rate_limit_exceeded", "message": "Limite de requisições excedido. Tente novamente em 42 segundos.", "requestId": "req_…" }}Limites por operação
Operações sensíveis ou caras têm limite próprio, menor que o padrão:
- POSTAutocadastro: criar a clínica do usuário autenticado (teste grátis do plano)
/v1/signupLimite: 5 requisições / 3600 s por IP. - GETContexto aprovado da clínica (perfil para os agentes)
/v1/clinic/contextLimite: 300 requisições / 60 s por token, clínica e agente. - PUTCadastrar/trocar o WhatsApp do usuário (zera a verificação)
/v1/users/{id}/whatsappLimite: 30 requisições / 3600 s. - POSTConfirmar o WhatsApp do usuário (somente admin da clínica)
/v1/users/{id}/whatsapp/verifyLimite: 30 requisições / 3600 s. - POSTConvidar usuário (e-mail + perfil)
/v1/invitationsLimite: 20 requisições / 3600 s. - POSTReenviar convite (gera novo link e renova a validade)
/v1/invitations/{id}/resendLimite: 20 requisições / 3600 s. - POSTAceitar convite (usuário convidado, já autenticado na plataforma)
/v1/invitations/acceptLimite: 10 requisições / 600 s. - POSTApresentar dado operacional estruturado a partir de mensagem do dono (não grava no cadastro)
/v1/owner-structured/changesLimite: 60 requisições / 60 s. - POSTGravar no cadastro a alteração confirmada por escrito pelo dono
/v1/owner-structured/changes/{id}/confirmLimite: 60 requisições / 60 s. - POSTEnviar mensagem (humano ou agente) / registrar recebida (token de serviço)
/v1/conversations/{id}/messagesLimite: 60 requisições / 60 s. - POSTRegistrar mensagem recebida do paciente (gateway; atômico e idempotente)
/v1/inbound/messagesLimite: 600 requisições / 60 s. - POSTObservar os gates F02 do agente (sem autorizar execução)
/v1/agents/{key}/preflightLimite: 60 requisições / 60 s. - POSTPublicar passos de uma execução em andamento (token de serviço)
/v1/agents/{key}/executions/eventsLimite: 1200 requisições / 60 s. - POSTEnviar mensagem para a Renata (um turno por vez, idempotente)
/v1/onboarding/messagesLimite: 60 requisições / 60 s. - POSTTentar de novo: reenviar a mensagem à Renata (mesmo evento)
/v1/onboarding/messages/{id}/retryLimite: 30 requisições / 60 s. - POSTPropor fato do perfil da clínica a partir de mensagem do dono (Lívia)
/v1/clinic/profile/proposalsLimite: 120 requisições / 60 s. - POSTApresentar pedido do dono (finance): valida e devolve a pergunta de confirmação — nada é executado
/v1/owner-commands/financeLimite: 60 requisições / 60 s. - POSTApresentar pedido do dono (schedule): valida e devolve a pergunta de confirmação — nada é executado
/v1/owner-commands/scheduleLimite: 60 requisições / 60 s. - POSTApresentar pedido do dono (registry): valida e devolve a pergunta de confirmação — nada é executado
/v1/owner-commands/registryLimite: 60 requisições / 60 s. - POSTConfirmar pedido do dono com o "sim" escrito: executa (direct) ou abre o item de aprovação (approval)
/v1/owner-commands/{id}/confirmLimite: 60 requisições / 60 s. - GETLeitura mascarada para o dono (entradas, agenda do dia, leads, achar paciente)
/v1/owner-commands/reads/{operation}Limite: 60 requisições / 60 s. - POSTReenviar nota fiscal por e-mail
/v1/billing/invoices/{id}/resendLimite: 5 requisições / 600 s. - POSTEnviar imagens (prints) para virar rascunho de conhecimento
/v1/knowledge/attachmentsLimite: 6 requisições / 60 s por token. - POSTTestar conexão
/v1/integrations/{id}/testLimite: 10 requisições / 60 s. - GETExportar histórico (CSV, UTF-8 com BOM, até 10.000 linhas)
/v1/audit-log/exportLimite: 5 requisições / 60 s. - POSTPedir exportação ou exclusão dos meus dados (LGPD)
/v1/me/data-requestsLimite: 3 requisições / 3600 s.
Tamanho das requisições
- Corpo JSON: até 1 MB. Acima disso, 413 payload_too_large.
- Upload de arquivo (multipart): até 2 MB por arquivo; um arquivo por requisição, exceto o envio de imagens para a base de conhecimento (até 12).
- Listas: até 100 itens por página.