Limites e idempotência

Limites de uso

O contrato 1.0.x não define um limite de taxa por requisição nem devolve cabeçalhos de cota. Isso não significa volume ilimitado: significa que o limite que importa é o do canal. Mensagem de WhatsApp fora do padrão de uso aceitável derruba a linha, e nenhuma cota da API protege disso. Trate a API como um canal de conversa, não de disparo em massa.

O que o servidor aplica hoje:

Quando um limite contratual por requisição existir, ele entra na referência com os cabeçalhos correspondentes e no changelog, antes de valer.

Idempotência

Repetir um pedido por timeout ou falha de rede não pode duplicar o efeito. O Nexus resolve isso de duas formas.

Chave natural

POST /api/wa/instances usa o instanceId como chave natural. Repetir a criação com o mesmo nome responde 409 e nunca cria uma segunda linha. Não existe criação implícita de "nova" por repetição.

Chave de idempotência

POST /api/send aceita o cabeçalho Idempotency-Key (entre 16 e 128 caracteres) ou o campo idempotencyKey no corpo. O mesmo valor, na mesma conta e na mesma operação, reaproveita a intenção já registrada em vez de enfileirar um segundo envio.

curl -X POST https://nexus.socialfy.me/api/send \
  -H "x-api-key: nx_acct_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-48213-confirmacao" \
  -d '{"instanceId":"comercial-sp","to":"+5511999990000","type":"text","message":"Pedido confirmado."}'

Regras para a chave funcionar a seu favor:

• Gere a chave a partir da intenção (o pedido, o evento, o lembrete), não do instante. pedido-48213-confirmacao repete bem; um timestamp não repete nunca.
• Reutilize a mesma chave só ao repetir a mesma operação com o mesmo conteúdo. Conteúdo diferente pede chave diferente.
• Guarde a chave do seu lado junto do registro que originou o envio. É ela que permite a repetição segura depois de um timeout.

O que fazer em timeout

1. Não dispare de novo às cegas.
2. Repita a mesma requisição com a mesma Idempotency-Key. Se a primeira entrou, a segunda reaproveita; se não entrou, a segunda vale como primeira.
3. Confirme pelo estado ou pelo webhook message_sent ou message_failed.

Tamanhos e formatos