EntrarTeste grátis

API · Atualizado em 12/10/2026

Limites de uso e idempotência na API

Conheça os limites de chamadas por chave, de corpo e de arquivo, e use o cabeçalho Idempotency-Key para repetir escritas sem duplicar nada.

Neste artigo
  1. Quando usar
  2. Limites por chave
  3. Limites de tamanho e de lote
  4. Idempotência com Idempotency-Key
  5. Resultado esperado
  6. Problemas comuns
  7. Boas práticas
  8. Próximos passos
  9. Perguntas frequentes

Para proteger a operação de todos, cada chave tem um teto de chamadas. E, para que uma falha de rede não vire mensagem duplicada, as escritas aceitam um cabeçalho de idempotência: repetir a mesma chamada não repete o efeito.

Quando usar

Ao dimensionar uma integração que envia muitas chamadas, e sempre que uma escrita (enviar mensagem, abrir ticket, criar contato) puder ser repetida por retry automático.

Limites por chave

LimiteValor padrãoObservações
Chamadas por segundo20Vale para todas as rotas /v1 que a chave alcança, leituras incluídas
Chamadas por minuto600Contador independente do anterior
POST /messages (raiz, estilo Blip)10 por segundoContador próprio
POST /notifications (raiz, estilo Blip)20 por segundoContador próprio
POST /commands (raiz, estilo Blip)20 por segundoContador próprio
Falhas de autenticação20 por minuto, por IPSó falhas contam. Sucesso nunca conta

Ao passar do limite, a API responde 429 com o código rate_limited e o cabeçalho Retry-After, em segundos:

{
  "error": {
    "code": "rate_limited",
    "message": "Limite de requisições da chave excedido. Tente de novo depois do prazo em Retry-After.",
    "detalhe": { "retryAfterSeconds": 1 }
  }
}

Os limites são compartilhados entre todas as réplicas da API, então não dá para "burlar" abrindo conexões em paralelo.

Limites de tamanho e de lote

Valores padrão da plataforma.

ItemLimite
Corpo JSON1 MB
Upload de arquivo (POST /v1/attachments)100 MB por arquivo; áudio e vídeo até 16 MB
Arquivos por mensagem10
Texto de mensagem4096 caracteres; legenda de mídia no WhatsApp, 1024
Contatos por disparo de mensagem ativa15
Destinatários por campanha5000
Itens por página100
Período de relatórios90 dias (histórico de conversas por chave: 92)

Idempotência com Idempotency-Key

Envie o cabeçalho Idempotency-Key em qualquer escrita (POST, PUT, PATCH, DELETE). O valor é seu: de 1 a 128 caracteres ASCII visíveis, como um UUID.

  1. Gere um valor novo para cada operação que quer executar uma única vez.
  2. Envie a chamada com o cabeçalho.
  3. Se não souber se ela chegou (timeout, queda de rede), repita exatamente a mesma chamada, com o mesmo cabeçalho.
curl -s -X POST https://http.pipebr.app/v1/contacts/b3a1c9de-0000-4000-8000-000000000010/tickets \
  -H "Authorization: Bearer $PIPE_CHAVE" \
  -H "Idempotency-Key: 6f1d2a52-0000-4000-8000-0000000000aa" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Cliente pediu atendimento humano"}'

O que acontece:

SituaçãoResposta
Primeira chamada com a chaveExecuta e guarda a resposta de sucesso por 24 horas
Mesma chave, mesmo método, caminho e corpoDevolve a resposta guardada, com o cabeçalho Idempotent-Replayed: true, sem executar de novo
Mesma chave com outro método, caminho ou corpo409 idempotency_conflict
Mesma chave enquanto a primeira ainda roda409 idempotency_in_progress
Chamada que deu erro (não 2xx)Não é guardada. Pode repetir com a mesma chave
Upload multipart com o cabeçalho422 idempotency_unsupported

A chave de idempotência vale por chave de API: duas integrações podem usar o mesmo valor sem se misturar.

Idempotência pelo id do envelope (estilo Blip)

Na rota POST /commands e nas rotas POST /messages e POST /notifications, a deduplicação usa o campo id do envelope, como na Blip. Veja Compatibilidade com a Blip.

Resultado esperado

Sua integração respeita o limite sem perder chamadas e repete escritas sem duplicar mensagens, tickets ou contatos.

Problemas comuns

  • 429 mesmo com poucas chamadas: o limite é por chave, não por integração. Várias rotinas usando a mesma chave dividem o mesmo teto. Use uma chave por rotina.
  • 429 por falhas de autenticação: uma chave errada em loop bloqueia aquele IP por até 1 minuto, inclusive para chamadas corretas vindas do mesmo IP.
  • 409 idempotency_conflict: você reaproveitou um valor de Idempotency-Key em outra operação. Gere um valor novo por operação.

Boas práticas

  • Implemente espera crescente ao receber 429 ou 5xx e respeite o Retry-After.
  • Gere a Idempotency-Key uma vez por operação e guarde junto do registro no seu sistema, para reaproveitar nos retries.
  • Para envios em volume, prefira campanhas, que têm fila e ritmo próprios.

Próximos passos

Perguntas frequentes

Quantas chamadas por segundo posso fazer?

Por padrão, 20 por segundo e 600 por minuto para cada chave. Passou disso, a resposta é 429 com Retry-After.

Para que serve o Idempotency-Key?

Para repetir uma escrita com segurança. Se a rede falhar e você reenviar a mesma chamada com a mesma chave de idempotência, o Pipe devolve a resposta guardada e não executa de novo.

Por quanto tempo a resposta fica guardada?

24 horas, por chave de API.

Respostas de erro ficam guardadas?

Não. Depois de corrigir o problema, você pode repetir a chamada com a mesma Idempotency-Key.