Ir para o conteúdo

Limites do plano e erros

Como a API responde quando o plano chega ao limite e o que significa cada erro.

Os limites vêm do seu plano e valem para a API inteira: pela área do cliente ou chamando a API direto, as regras são as mesmas. Veja os limites do seu plano em Plano, na área do cliente.

Formato dos erros

Todo erro é um JSON com error, uma mensagem estável em inglês. Quando há um código para tratar no seu programa, ele vem em code:

json
{"error": "Plan limit reached: max_instances.", "code": "plan_limit", "limit": "max_instances"}

Trate pelo code e pelo status HTTP, não pelo texto de error.

Limites do plano

StatuscodeQuando
403plan_limitUm limite numérico foi atingido. limit diz qual: max_instances, max_messages_per_month, max_contacts, max_flows, max_campaigns_per_month...
403plan_feature_disabledA função não está no plano. feature diz qual: marketing_enabled, flows_enabled, queue_enabled...
503usage_unavailableA API não conseguiu conferir o uso do mês. Tente de novo em instantes.
403ACCOUNT_SUSPENDEDA conta está suspensa ou cancelada por cobrança. As leituras continuam, os envios param.

Na importação de contatos, o 403 plan_limit vem com os contadores do que foi gravado. Leia-os: não é um desfazer.

Número alugado conta em max_instances como qualquer outro, desde a reserva (o pagamento aberto) até o fim do aluguel. Sem vaga no plano, o aluguel é barrado já na compra, e a entrega confere a vaga de novo. Veja Alugar um número.

Chave de API

Os erros de uma chave de API (wck_...) que existe mas não abre o que foi pedido:

StatuscodeQuando
403CLIENT_KEY_SCOPEA rota está fora dos escopos da chave (por exemplo, Marketing com uma chave só de Números), o número não está na lista da chave, ou a rota não abre para chave de API (criar ou apagar número, QR, webhook, cluster, aquecimento, caixa de entrada).
403SENDER_NOT_ALLOWEDUma campanha ou um fluxo usaria, para enviar, um número ou cluster fora da lista da chave, ou um fluxo aponta para outro fluxo ou campanha que a chave não vê.
404A campanha, o fluxo ou a execução existe, mas envia por números fora da lista da chave: para essa chave, ela não existe. Também um cluster que não existe.
401Rota que só a chave global abre (as de /api/v1/admin), ou chave revogada.
503A API não conseguiu conferir a chave agora ("error": "client key check unavailable"). Tente de novo em instantes.

Outros erros

StatusSignificado
400Corpo ou parâmetro inválido. A mensagem diz o campo.
401Chave ausente, errada, revogada ou que não vale para esta rota (por exemplo, a chave de um número usada em outro número ou em GET /api/v1/instances).
403Limite ou função do plano, conta suspensa ou escopo da chave de API (veja acima).
404O recurso não existe (ou não é visível para a chave de API), ou o token do webhook de entrada não vale.
409Conflito de estado: fluxo não publicado, execução já terminada, revisão desatualizada; INSTANCE_REMOVED numa escrita da caixa de entrada de um número removido.
410INSTANCE_REMOVED: o número foi removido (veja Números).
413Corpo grande demais.
422Validação de negócio: fluxo inválido na publicação, público grande demais.
429Muitas chamadas. Espere o tempo de Retry-After (em segundos) e tente de novo.
502Erro do servidor do WhatsApp num envio. Tente de novo em instantes.
503O número não está conectado, ou o serviço está temporariamente indisponível.

Quando o plano baixa, o que passa do limite novo fica pausado pelo plano (fluxos, campanhas, aquecimentos e números de cluster aparecem com paused_by_plan/pausedByPlan; na área do cliente, "Pausado pelo plano"). Volta sozinho quando o plano sobe.

Ritmo de chamadas

A API limita as chamadas por chave. Ao receber 429, espere o Retry-After e repita. Não repita em laço sem espera. Envios em massa ficam melhores numa campanha ou na fila de um cluster, que controlam o ritmo sozinhas.

Envio para quem não tem WhatsApp

O envio responde 400 com "code": "RECIPIENT_NOT_ON_WHATSAPP". O erro não afeta a saúde do seu número. Não repita o envio.