Limites e idempotência

Limites de requisições

O quê	Limite	Ao passar
Chamadas à API por app e empresa	600 por minuto	429 ERR_LIMITE_REQUISICOES
Chamadas à API por chave de integração	600 por minuto	429 ERR_LIMITE_REQUISICOES
Renovação de token (grant_type=refresh_token)	300 por minuto, por IP e client_id	429
Chaves de integração inválidas	30 por minuto, por IP	429
Envio para número avulso (destino.numero)	200 por dia por app e empresa (dia em America/Sao_Paulo); nas chaves, somado entre as chaves da empresa	429 ERR_LIMITE_ENVIO_AVULSO, com Retry-After até a meia-noite

Os limites são por empresa: um cliente grande não consome o limite dos outros clientes do seu app.

Boas práticas:

• Ao receber 429, respeite Retry-After quando ele vier; sem ele, espere alguns segundos e aumente a espera a cada nova recusa.
• Prefira os webhooks a consultas periódicas ("polling"). Quando precisar consultar, use os filtros atualizadoDesde de tickets e oportunidades para buscar só o que mudou.
• Envie mensagens por destino.pessoaId ou destino.contatoId. Esses envios não contam no teto de número avulso.

Idempotência

POST que cria registro ou envia mensagem exige o cabeçalho Idempotency-Key (ex.: criar pessoa, criar oportunidade, enviar mensagem, anotar, transferir e fechar ticket). A referência de cada endpoint mostra quando ele é obrigatório.

POST /plataforma/v1/mensagens HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json
Idempotency-Key: lembrete-8812-345

• Mesma chave, mesma empresa e mesma rota em até 7 dias devolve a mesma resposta, sem repetir o efeito. A resposta repetida vem com o cabeçalho Idempotency-Replay: true.
• Mesma chave com outro corpo ou em outra rota: 422 ERR_IDEMPOTENCY_KEY_REUTILIZADA.
• Chave ainda em processamento: 409 ERR_REQUISICAO_EM_ANDAMENTO.
• Respostas 409, 429 e 5xx não ficam gravadas: a mesma chave pode ser reenviada.
• Gere a chave a partir do seu identificador do fato (ex.: lembrete-<id do lembrete>-<id da pessoa>), não do número da tentativa. Assim, se a primeira tentativa der timeout depois de a mensagem sair, a nova tentativa recebe a resposta gravada em vez de enviar de novo.

PATCH, PUT e ações de estado (mover, ganhar, perder, reabrir, opt-out) não exigem a chave, porque repeti-las dá o mesmo resultado.

Assinatura da empresa

Se a assinatura da empresa estiver vencida ou bloqueada, as escritas recebem 403 ERR_ASSINATURA_VENCIDA ou 403 ERR_ASSINATURA_BLOQUEADA, e as leituras continuam funcionando. Essa resposta não é gravada na idempotência: depois que a empresa regularizar, a mesma chave funciona.

Registro das chamadas

Toda chamada do seu app é registrada (app, empresa, rota, status e duração). No Portal do parceiro você vê as chamadas e as entregas de webhook dos últimos 30 dias. A leitura de conversas registra também quais atendimentos foram lidos, sem o conteúdo.