Limites e rate limit

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: 60

Limit é 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.

1{2  "error": {3    "code": "rate_limit_exceeded",4    "message": "Limite de requisições excedido. Tente novamente em 42 segundos.",5    "requestId": "req_…"6  }7}

Limites por operação

Operações sensíveis ou caras têm limite próprio, menor que o padrão:

• OperaçãoLimite
• POSTAutocadastro: criar a clínica do usuário autenticado (teste grátis do plano)/v1/signupLimite: 5 requisições / 3600 s por IP.
• 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.
• 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.
• POSTReenviar nota fiscal por e-mail/v1/billing/invoices/{id}/resendLimite: 5 requisições / 600 s.
• 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): um arquivo por requisição, até 2 MB.
• Listas: até 100 itens por página.