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.
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.
| Limite | Padrão | Ao passar dele |
|---|---|---|
| Requisições por IP | 600 por minuto (janela fixa) | 429 com Retry-After |
| Autenticações com falha (chave errada) por IP | 20 a cada 5 minutos | 429 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.
| Limite | Padrão | Efeito |
|---|---|---|
| Aviso de consumo | A partir de 80% do limite diário ou mensal | O envio é aceito com o cabeçalho X-Usage-Warning |
| Corte | 110% 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.
| Regra | Padrão | Ao passar dele |
|---|---|---|
| Envios por número | 3 por minuto, 60 por hora, 200 por dia | Espera na fila |
| Intervalo entre dois envios | Aleatório, de 3 a 8 segundos | Espera na fila |
| Mesmo destinatário | Pelo menos 30 segundos entre duas mensagens | Espera na fila |
| Destinatários novos | 100 por 24 horas | 429 new_recipient_cap_reached com Retry-After |
| Contato conhecido | Trocou mensagem com o número nos últimos 28 dias, depois da conexão atual | Não conta como destinatário novo |
| Pausa por falhas | 5 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ão | Por minuto | Por hora | Por dia | Destinatários novos por 24 horas |
|---|---|---|---|---|
| Até 6 horas | 1 | 5 | 20 | 5 |
| 6 a 24 horas | 1 | 10 | 50 | 10 |
| 1 a 3 dias | 1 | 20 | 100 | 20 |
| 3 a 7 dias | 1 | 30 | 150 | 30 |
| 7 a 14 dias | 2 | 45 | 200 | 50 |
| Depois de 14 dias | 3 | 60 | 200 | 100 |
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"const res = await fetch(`https://api.apiwpp.com/connections/${process.env.CONNECTION_ID}/queue`, {
headers: { Authorization: `Bearer ${process.env.API_KEY}` },
})
const { limits, usage, warmup } = await res.json()
console.log(`Hoje: ${usage.day}/${limits.perDay}; novos em 24 h: ${usage.newRecipients}/${limits.newRecipientsPerDay ?? '∞'}`)
if (warmup.isInWarmup) console.log('Em aquecimento até', new Date(warmup.endsAt).toISOString()){
"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
| Limite | Valor | Detalhes |
|---|---|---|
clientRef | Até 200 caracteres; reservado por 7 dias na conexão | Idempotência |
Reserva provisória de um clientRef | Expira sozinha em 60 segundos se o enfileiramento não terminar | Idempotência |
typingDelay | Padrão de 1500 milissegundos | Enviar mensagens |
Arquivo de media.url | Até 50 MB, download em até 30 segundos, até 3 redirecionamentos | Enviar mensagens |
Vínculo do clientRef com os status | 72 horas em message.delivery | Idempotê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.
| Limite | Valor | Ao passar dele |
|---|---|---|
| Mensagens que podem ser editadas ou apagadas | Só as enviadas pela API por esta conexão nas últimas 72 horas | 404 |
| Janela de edição | 15 minutos depois do envio | 409 edit_window_closed |
text da edição | De 1 a 4096 caracteres | 400 |
messageIds em marcar como lidas | De 1 a 100 por chamada | 400 |
Contatos
| Limite | Valor | Ao passar dele |
|---|---|---|
phones em verificar números | Até 100 por chamada | 400 |
Pareamento
Detalhes em Parear um número.
| Limite | Valor | Ao passar dele |
|---|---|---|
| Código de pareamento | 8 caracteres, válido até expiresAt | Peça outro |
| Pedidos de código por conexão | Um a cada 30 segundos | 429 pairing_code_too_soon com Retry-After |
| Códigos por número de telefone | 5 por hora | 429 pairing_code_too_soon com Retry-After |
phone do pedido de código | De 8 a 32 caracteres | 400 |
| Aquecimento depois do pareamento | 14 dias | Veja Aquecimento |
Chaves de API
Detalhes em Autenticação.
| Limite | Valor |
|---|---|
name da chave | De 1 a 100 caracteres |
scopes | Pelo menos 1, e só escopos que a chave chamadora tem |
overlapSeconds ao rotacionar | Padrão de 24 horas (86400), de 0 a 7 dias (604800) |
| Chaves revogadas ou expiradas na listagem | As 100 mais recentes |
Webhooks
Detalhes em Webhooks e assinatura.
| Limite | Padrão |
|---|---|
Tempo para o seu endpoint responder 2xx | 10 segundos |
| Tentativas por evento | 6 (a primeira e mais 5, depois de cerca de 2, 4, 8, 16 e 32 segundos) |
| Pausa das entregas do projeto | Depois de 5 falhas seguidas: 30 segundos, dobrando a cada teste que falha, até 5 minutos |
| Idade máxima de um evento não entregue | 24 horas, depois fica dead |
| Entregas esperando nova tentativa por projeto | 10 000; além disso, as novas falhas vão direto para dead |
Tolerância de X-Sales-Timestamp no seu verificador | 300 segundos |
| Payload guardado no registro de entregas | Até 256 KB (maior que isso não pode ser reenviado) |
| Reenviar entregas mortas | Até 1000 por chamada |
| Testar webhook | 10 segundos para o endpoint responder |
Mídia recebida
| Limite | Padrão | Detalhes |
|---|---|---|
Validade da URL de media.url em message.incoming | 24 horas (até media.expiresAt) | Baixar mídia |
| Arquivo guardado na apiwpp | 24 horas; depois a URL responde 404 | Baixar mídia |
Consultas, uso e registros
| Parâmetro | Valores | Operação |
|---|---|---|
limit | De 1 a 200, padrão 60 | Listar mensagens, Entregas de webhook |
days | Padrão 30, no máximo 366 | Uso do projeto |
days | De 1 a 90, padrão 14 | Uso diário |
hours | De 1 a 168, padrão 24 | Histórico de heartbeats |
| Dado | Retençã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 uso | Nã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
429foi. - Códigos de erro: cada
errorecodeque um limite pode devolver. - Cabeçalhos:
Retry-After,X-Usage-Percent,X-Usage-Warninge os cabeçalhos de webhook.