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:
{"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
| Status | code | Quando |
|---|---|---|
403 | plan_limit | Um limite numérico foi atingido. limit diz qual: max_instances, max_messages_per_month, max_contacts, max_flows, max_campaigns_per_month... |
403 | plan_feature_disabled | A função não está no plano. feature diz qual: marketing_enabled, flows_enabled, queue_enabled... |
503 | usage_unavailable | A API não conseguiu conferir o uso do mês. Tente de novo em instantes. |
403 | ACCOUNT_SUSPENDED | A 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:
| Status | code | Quando |
|---|---|---|
403 | CLIENT_KEY_SCOPE | A 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). |
403 | SENDER_NOT_ALLOWED | Uma 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ê. |
404 | A 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. | |
401 | Rota que só a chave global abre (as de /api/v1/admin), ou chave revogada. | |
503 | A API não conseguiu conferir a chave agora ("error": "client key check unavailable"). Tente de novo em instantes. |
Outros erros
| Status | Significado |
|---|---|
400 | Corpo ou parâmetro inválido. A mensagem diz o campo. |
401 | Chave 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). |
403 | Limite ou função do plano, conta suspensa ou escopo da chave de API (veja acima). |
404 | O recurso não existe (ou não é visível para a chave de API), ou o token do webhook de entrada não vale. |
409 | Conflito 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. |
410 | INSTANCE_REMOVED: o número foi removido (veja Números). |
413 | Corpo grande demais. |
422 | Validação de negócio: fluxo inválido na publicação, público grande demais. |
429 | Muitas chamadas. Espere o tempo de Retry-After (em segundos) e tente de novo. |
502 | Erro do servidor do WhatsApp num envio. Tente de novo em instantes. |
503 | O 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.