Pular para o conteúdo

Limites

Todos os números da apiwpp numa página: requisições, cota, ritmo de envio por número, pareamento, chaves, webhooks, mídia e registros.

Ver em Markdown

Esta página reúne todos os números da apiwpp para consulta rápida. Cada linha aponta para o guia que explica a regra. Todos são os padrões da apiwpp; os limites de envio por minuto, hora e dia de um projeto podem ser ajustados pela nossa equipe, e os que valem agora para um número estão em GET /connections/{id}/queue.

Requisições à API

Contadas por IP de origem, antes da autenticação. Detalhes em Limites de envio.

LimitePadrãoAo passar dele
Requisições por IP600 por minuto (janela fixa)429 com Retry-After
Autenticações com falha (chave errada) por IP20 a cada 5 minutos429 com Retry-After pelo resto da janela

As requisições com credencial (certa ou errada) e as anônimas têm cotas separadas. Toda resposta contada traz x-ratelimit-limit, x-ratelimit-remaining e x-ratelimit-reset.

Cota do plano

Os planos LITE e PRO não têm cota de mensagens: esta seção vale só para planos com um limite diário ou mensal. Nesses, a cota é da organização e soma os envios de todos os projetos dela, com o dia e o mês contados em UTC. Detalhes em Limites de envio.

LimitePadrãoEfeito
Aviso de consumoA partir de 80% do limite diário ou mensalO envio é aceito com o cabeçalho X-Usage-Warning
Corte110% do limite (a margem absorve requisições simultâneas)429 com X-Usage-Percent, sem enfileirar

Ritmo de envio de cada número

Os limites por minuto, hora e dia não recusam o envio: a mensagem espera na fila. Só o limite de destinatários novos responde na hora. Detalhes em Limites de envio.

RegraPadrãoAo passar dele
Envios por número3 por minuto, 60 por hora, 200 por diaEspera na fila
Intervalo entre dois enviosAleatório, de 3 a 8 segundosEspera na fila
Mesmo destinatárioPelo menos 30 segundos entre duas mensagensEspera na fila
Destinatários novos100 por 24 horas429 new_recipient_cap_reached com Retry-After
Contato conhecidoTrocou mensagem com o número nos últimos 28 dias, depois da conexão atualNão conta como destinatário novo
Pausa por falhas5 falhas seguidas (sem uma pausa de mais de 5 minutos entre elas)A fila do número para por 1 hora e retoma sozinha

Aquecimento

Nos 14 dias depois de conectado, um número segue limites menores. Detalhes em Aquecimento de um número recém-conectado.

Desde a conexãoPor minutoPor horaPor diaDestinatários novos por 24 horas
Até 6 horas15205
6 a 24 horas1105010
1 a 3 dias12010020
3 a 7 dias13015030
7 a 14 dias24520050
Depois de 14 dias360200100

Nenhuma etapa passa dos limites normais do número. Parear de novo (outro número, ou o mesmo depois de um logout) recomeça o aquecimento e zera os contatos conhecidos.

Para ver os limites, o consumo e o aquecimento de um número agora:

curl -s https://api.apiwpp.com/connections/$CONNECTION_ID/queue \
  -H "Authorization: Bearer $API_KEY"
200
{
  "pending": 1,
  "scheduled": 2,
  "limits": { "perMinute": 3, "perHour": 60, "perDay": 200, "newRecipientsPerDay": 100 },
  "usage": { "minute": 1, "hour": 12, "day": 40, "newRecipients": 7 },
  "warmup": { "createdAt": 1789646400000, "messagesSent": 40, "isInWarmup": false, "endsAt": 1790856000000 }
}

Envio de mensagens

LimiteValorDetalhes
clientRefAté 200 caracteres; reservado por 7 dias na conexãoIdempotência
Reserva provisória de um clientRefExpira sozinha em 60 segundos se o enfileiramento não terminarIdempotência
typingDelayPadrão de 1500 milissegundosEnviar mensagens
Arquivo de media.urlAté 50 MB, download em até 30 segundos, até 3 redirecionamentosEnviar mensagens
Vínculo do clientRef com os status72 horas em message.deliveryIdempotência

Operações de mensagem (PRO)

Exigem um plano com operações de mensagem; sem ele, a resposta é 403 plan_feature_required. Detalhes em Operações de mensagem.

LimiteValorAo passar dele
Mensagens que podem ser editadas ou apagadasSó as enviadas pela API por esta conexão nas últimas 72 horas404
Janela de edição15 minutos depois do envio409 edit_window_closed
text da ediçãoDe 1 a 4096 caracteres400
messageIds em marcar como lidasDe 1 a 100 por chamada400

Contatos

LimiteValorAo passar dele
phones em verificar númerosAté 100 por chamada400

Pareamento

Detalhes em Parear um número.

LimiteValorAo passar dele
Código de pareamento8 caracteres, válido até expiresAtPeça outro
Pedidos de código por conexãoUm a cada 30 segundos429 pairing_code_too_soon com Retry-After
Códigos por número de telefone5 por hora429 pairing_code_too_soon com Retry-After
phone do pedido de códigoDe 8 a 32 caracteres400
Aquecimento depois do pareamento14 diasVeja Aquecimento

Chaves de API

Detalhes em Autenticação.

LimiteValor
name da chaveDe 1 a 100 caracteres
scopesPelo menos 1, e só escopos que a chave chamadora tem
overlapSeconds ao rotacionarPadrão de 24 horas (86400), de 0 a 7 dias (604800)
Chaves revogadas ou expiradas na listagemAs 100 mais recentes

Webhooks

Detalhes em Webhooks e assinatura.

LimitePadrão
Tempo para o seu endpoint responder 2xx10 segundos
Tentativas por evento6 (a primeira e mais 5, depois de cerca de 2, 4, 8, 16 e 32 segundos)
Pausa das entregas do projetoDepois de 5 falhas seguidas: 30 segundos, dobrando a cada teste que falha, até 5 minutos
Idade máxima de um evento não entregue24 horas, depois fica dead
Entregas esperando nova tentativa por projeto10 000; além disso, as novas falhas vão direto para dead
Tolerância de X-Sales-Timestamp no seu verificador300 segundos
Payload guardado no registro de entregasAté 256 KB (maior que isso não pode ser reenviado)
Reenviar entregas mortasAté 1000 por chamada
Testar webhook10 segundos para o endpoint responder

Mídia recebida

LimitePadrãoDetalhes
Validade da URL de media.url em message.incoming24 horas (até media.expiresAt)Baixar mídia
Arquivo guardado na apiwpp24 horas; depois a URL responde 404Baixar mídia

Consultas, uso e registros

ParâmetroValoresOperação
limitDe 1 a 200, padrão 60Listar mensagens, Entregas de webhook
daysPadrão 30, no máximo 366Uso do projeto
daysDe 1 a 90, padrão 14Uso diário
hoursDe 1 a 168, padrão 24Histórico de heartbeats
DadoRetenção padrão
Registro de mensagens e registro de entregas de webhook (com os payloads)7 dias
Eventos de conexão (histórico de heartbeats)30 dias
Totais de usoNão são apagados pela limpeza

A limpeza roda a cada 6 horas, então uma linha pode durar algumas horas além do prazo. Detalhes em Uso e registros.

Próximos passos

  • Limites de envio: por que cada limite existe e como saber qual 429 foi.
  • Códigos de erro: cada error e code que um limite pode devolver.
  • Cabeçalhos: Retry-After, X-Usage-Percent, X-Usage-Warning e os cabeçalhos de webhook.
Esta página ajudou? · Atualizado em 29 set 2026