Limites e boas práticas
Requisições por minuto
| Limite | Valor |
|---|---|
| Por chave de API | 600 requisições por minuto (janela fixa) |
| Resposta ao ultrapassar | 429 API_KEY_RATE_LIMITED |
Quando receber um 429, espere e tente de novo com espera crescente (1 s, 2 s, 4 s…) e um pequeno fator aleatório. Os cabeçalhos X-RateLimit-* chegarão na próxima versão; até lá, meça você mesmo o ritmo.
Tamanhos
| Operação | Máximo |
|---|---|
POST /contacts/bulk |
500 ids por chamada, 20 etiquetas |
POST /campaigns/{id}/recipients por ids |
20.000 ids por chamada |
| Etiquetas por contato | 50, de até 60 caracteres |
| Nota de contato | 4.000 caracteres |
Tamanho de página (pageSize) |
100 (padrão 20) |
Idempotência
Criar duas vezes o mesmo contato não duplica: a segunda chamada responde 409 CONTACT_PHONE_EXISTS com o contactId do existente. Enviar duas vezes uma campanha responde 400 («já foi enviada»). Adicionar duas vezes o mesmo público não duplica destinatários (alreadyIn os contabiliza). Para as demais operações, guarde o id que devolvemos e não repita a criação se a resposta se perdeu; o cabeçalho Idempotency-Key chegará com a próxima versão.
Tempos
Responda aos seus webhooks em menos de 10 segundos (basta um 200 imediato e processar depois). As requisições à API costumam levar menos de 300 ms; defina um tempo máximo de 30 s no seu cliente.
Datas e fusos horários
Todas as datas vão em ISO 8601 com fuso (2026-10-14T10:21:00.000Z). Ao agendar uma campanha, envie o fuso na data (2026-10-20T09:00:00+02:00).
Estabilidade
- A API é versionada na rota (
/api/v1). Adicionamos campos sem aviso; nunca removemos nem renomeamos campos dentro da mesma versão. - As mudanças são publicadas no changelog; as descontinuações são anunciadas com 6 meses de antecedência.
- Trate os valores de enumerações (
status,source,channelType) como listas abertas: podem aparecer valores novos.