Erros da API v2

Todo erro da API v2 vem com um código de status HTTP real e o mesmo formato JSON. Esta página lista cada code, o que ele significa e o que fazer. Cada resposta de erro traz em docs um link para o código nesta página.

O objeto de erro#

{
  "error": {
    "code": "not_cancellable",
    "message": "Only a waiting message can be cancelled.",
    "field": null,
    "docs": "https://wbiztool.com/docs/api/v2/errors/#not_cancellable",
    "request_id": "req_4f1c2a9b8e7d6c5b4a392817",
    "status": "sent"
  }
}

Alguns códigos trazem detalhes próprios, como status, count, used ou limit; eles aparecem junto com o código. Uma resposta com HTTP 401 também tem um cabeçalho WWW-Authenticate: Bearer realm="wbiztool", e as respostas com 429 (e o 409 idempotency_in_progress) têm Retry-After.

Em resumo: 4xx significa que a requisição precisa mudar (ou, no caso de 409 e 429, esperar); repeti-la sem mudanças dá a mesma resposta. 5xx significa um problema do nosso lado; tente de novo mais tarde, com a mesma Idempotency-Key.

Autenticação e limites#

api_v2_not_enabled#

HTTP 403. A API v2 não está disponível para este espaço de trabalho. Se você vir isso, fale conosco.

O que fazer: continue usando a API v1 por enquanto. O cartão Chaves de API v2 em Configurações → Chaves de API mostra quando ela estiver aberta para você.

missing_api_key#

HTTP 401. A requisição não tem o cabeçalho Authorization: Bearer …, ou ele está vazio ou usa outro esquema.

O que fazer: envie Authorization: Bearer wbz_live_… (ou wbz_test_…) em toda requisição. Veja Chaves.

invalid_api_key#

HTTP 401. A chave não é uma chave v2 do WbizTool: digitada errado, cortada ou não criada por nós.

O que fazer: copie a chave de novo, sem espaços nem aspas. Uma chave não pode ser exibida de novo depois de criada; se você a perdeu, crie uma nova em Configurações → Chaves de API.

v1_key_on_v2#

HTTP 401. A chave é uma chave da API v1 (40 caracteres, dígitos e de a a f). Chaves v1 funcionam só em /api/v1/.

O que fazer: crie uma chave v2 no cartão Chaves de API v2 em Configurações → Chaves de API, ou chame a API v1.

api_key_revoked#

HTTP 401. A chave foi revogada em Configurações → Chaves de API, ou o espaço de trabalho dela foi excluído ou desativado.

O que fazer: use outra chave ou peça a um Proprietário do espaço de trabalho que crie uma nova.

api_key_expired#

HTTP 401. A data de expiração da chave já passou.

O que fazer: peça a um Proprietário do espaço de trabalho que crie uma chave nova e substitua a antiga no seu app.

too_many_auth_failures#

HTTP 429. Mais de 30 requisições em um minuto vindas do seu endereço IP tinham uma chave errada. Retry-After é 60.

O que fazer: pare e corrija a chave no seu app; depois tente de novo após um minuto.

demo_account#

HTTP 403. Um espaço de trabalho de demonstração não pode usar a API.

O que fazer: cadastre-se para ter a sua própria conta e crie uma chave nela.

missing_scope#

HTTP 403. A chave não tem a permissão de que esta requisição precisa. required_scope no erro diz qual, como messages:send.

O que fazer: crie uma chave com essa permissão (não é possível adicionar permissões a uma chave existente). Veja Permissões.

rate_limited#

HTTP 429. A chave fez mais de 60 requisições neste minuto, ou mais de 10.000 hoje (UTC).

O que fazer: espere o número de segundos em Retry-After e tente de novo. Espalhe as requisições, use POST /messages/batch para muitos destinatários e webhooks em vez de consultar periodicamente. Veja Limites de requisições.

Requisição#

not_found#

HTTP 404. Não há nada neste endereço: o caminho está digitado errado ou não é um caminho da API v2.

O que fazer: compare o caminho com a referência, por exemplo /api/v2/messages, não /api/v2/message.

invalid_json#

HTTP 400. O corpo não é um JSON válido, muitas vezes por causa de uma vírgula sobrando no final ou de uma quebra de linha sem escape em text.

O que fazer: confira o JSON e escreva as quebras de linha dentro de strings como \n. Deixe a sua biblioteca HTTP montar o corpo (json= no Python requests, JSON.stringify no JavaScript).

unsupported_content_type#

HTTP 415. O corpo não foi enviado do jeito que este endpoint aceita: todos os endpoints aceitam application/json, exceto POST /media, que aceita multipart/form-data.

O que fazer: defina Content-Type: application/json e envie JSON, ou envie o upload como multipart com o campo file.

method_not_allowed#

HTTP 405. O caminho existe, mas não com este método, como PUT /messages/9817263.

O que fazer: use o método que a referência mostra. Uma alteração em um lembrete é PATCH; cancelar uma mensagem é DELETE.

request_too_large#

HTTP 413. O corpo da requisição é grande demais.

O que fazer: envie menos em uma requisição; por exemplo, divida uma lista longa em vários lotes.

validation_failed#

HTTP 400. A requisição não tem o formato certo: falta um campo obrigatório, um valor tem o tipo errado ou é longo demais, um campo não é conhecido, ou limit não está entre 1 e 100. field indica o primeiro problema e message o explica; errors lista os demais.

O que fazer: corrija o campo indicado em field. Os nomes de campo são em snake_case e campos desconhecidos são recusados, então procure erros de digitação como txt ou phone_number.

invalid_cursor#

HTTP 400. O cursor está danificado ou foi criado para filtros diferentes dos desta requisição.

O que fazer: envie exatamente o next_cursor que você recebeu, com os mesmos filtros da primeira página. Para mudar os filtros, comece de novo sem cursor.

invalid_idempotency_key#

HTTP 400. O cabeçalho Idempotency-Key está vazio, tem mais de 255 caracteres ou contém caracteres que não podem ser impressos.

O que fazer: use um UUID ou outra string curta de letras, dígitos e hifens.

idempotency_key_reused#

HTTP 422. Esta Idempotency-Key já foi usada nas últimas 24 horas com uma requisição diferente: outro método, caminho ou corpo.

O que fazer: use uma chave nova para cada nova requisição, e reutilize uma chave só para repetir exatamente a mesma requisição. Veja Idempotency-Key.

idempotency_in_progress#

HTTP 409. A primeira requisição com esta Idempotency-Key ainda está sendo processada. Retry-After é 1.

O que fazer: espere um segundo e envie a mesma requisição de novo: você vai receber a resposta da primeira.

internal_error#

HTTP 500. Algo deu errado do nosso lado. Nós somos avisados.

O que fazer: tente de novo mais tarde com a mesma Idempotency-Key, para o trabalho não ser feito duas vezes. Se continuar acontecendo, fale conosco com o request_id.

Mensagens#

text_required#

HTTP 400. A mensagem não tem text nem media, ou o texto tem só espaços. Para um lembrete, text é obrigatório.

O que fazer: envie text, media ou os dois.

text_too_long#

HTTP 400. text tem mais de 3.000 caracteres.

O que fazer: encurte-o ou divida-o em várias mensagens.

too_many_recipients#

HTTP 400. Um lote tem mais de 1.000 destinatários em to.

O que fazer: divida a lista em lotes de até 1.000, cada um com a sua própria Idempotency-Key.

invalid_datetime#

HTTP 400. Um horário (send_at, expires_at, since, until) não está em ISO 8601 com o deslocamento.

O que fazer: escreva-o como 2026-10-20T09:30:00+05:30 ou 2026-10-20T04:00:00Z. Um horário sem deslocamento, como 2026-10-20 09:30, é recusado porque é ambíguo. Em uma query string, escreva + como %2B.

invalid_phone#

HTTP 422. Um número de telefone (to.phone, ou phone ao conectar um número) não é um número válido em formato internacional com +.

O que fazer: escreva-o com + e o código do país, como +919876543210. Espaços e hifens não são problema; um 0 no início no lugar do código do país, sim.

invalid_username#

HTTP 422. to.username não é um nome de usuário do Telegram.

O que fazer: escreva @name, um link t.me/name ou tg: e um id de usuário. Veja Destinatários.

username_needs_telegram#

HTTP 422. Só é possível enviar para um nome de usuário do Telegram a partir de uma conta do Telegram, e from é um número de WhatsApp (ou, sem from, não há exatamente uma conta do Telegram conectada).

O que fazer: defina from como o id de uma conta do Telegram, ou envie para um número de telefone.

contact_not_found#

HTTP 422. Nenhum contato com este to.contact_id no espaço de trabalho.

O que fazer: confira o id (o contact_id de uma mensagem anterior, por exemplo) ou envie para to.phone.

media_not_found#

HTTP 422 ao enviar uma mensagem ou criar um lembrete com media.media_id; HTTP 404 em GET ou DELETE /media/{id}. Não há nenhum arquivo com este id no Diretório de mídia do espaço de trabalho, ou ele foi excluído.

O que fazer: confira o id com Listar arquivos ou envie o arquivo de novo.

invalid_media_url#

HTTP 422. media.url não é um link público http ou https: está malformado ou aponta para um endereço privado ou local.

O que fazer: use um link que qualquer pessoa na internet possa abrir, ou envie o arquivo e mande-o pelo media_id.

time_in_past#

HTTP 422. send_at ou expires_at já passou.

O que fazer: confira o horário e o deslocamento. Para enviar agora, deixe send_at de fora.

number_not_found#

HTTP 422 quando from (ou number_id ao conectar) não é um número deste espaço de trabalho; HTTP 404 em GET /numbers/{id}, também quando a chave não pode usar esse número.

O que fazer: obtenha o id certo em Listar números.

from_required#

HTTP 422. from está ausente, e o espaço de trabalho não tem nenhum número conectado ou tem mais de um, então não fica claro qual deve enviar. (Para uma chave limitada a alguns números: o único número conectado não é um dos números dela.)

O que fazer: envie from com o id do número que vai enviar.

number_not_allowed#

HTTP 403. A chave está limitada a alguns números, e esta requisição precisa de outro: from é outro número, um lembrete não indica um dos números dela, uma requisição de conexão adiciona um número ou indica outro, ou a requisição gerencia endpoints de webhook.

O que fazer: use um dos números da chave (number_ids em GET /me) ou uma chave que não seja limitada.

no_credits#

HTTP 402. O espaço de trabalho não tem mais mensagens no plano. Em um lote, requested e remaining dizem quantas foram pedidas e quantas restam.

O que fazer: envie menos mensagens, ou compre um plano ou mais mensagens; os planos pagos enviam mensagens ilimitadas. Veja Quando as mensagens acabam.

account_disabled#

HTTP 403. A conta do proprietário do espaço de trabalho está desativada, então o espaço de trabalho não pode enviar.

O que fazer: fale com o suporte.

number_daily_cap_reached#

HTTP 429. O número que envia já enviou 1.000 mensagens nas últimas 24 horas (uso justo), ou um lote não cabe no que resta: requested e room dizem quantas.

O que fazer: envie o restante mais tarde ou por outro número.

message_rejected#

HTTP 422. A mensagem não pôde entrar na fila; message diz o motivo. Nada foi salvo.

O que fazer: corrija o que message descreve e envie de novo.

message_not_found#

HTTP 404. Nenhuma mensagem com este id para esta chave: ela não existe, pertence a outro espaço de trabalho ou foi enviada por um número que a chave não pode usar. Uma chave de teste só vê as próprias mensagens de teste, e uma chave real nunca as vê.

O que fazer: confira o id e se você usa o mesmo tipo de chave (real ou de teste) que criou a mensagem.

not_cancellable#

HTTP 409. Só uma mensagem em espera (queued ou scheduled) pode ser cancelada, e esta não está mais em espera. status no erro diz o que ela é agora, como sent ou cancelled.

O que fazer: não há nada a cancelar. Uma mensagem que já foi enviada não pode ser recuperada.

Lembretes#

invalid_cron#

HTTP 400. schedule.cron não é uma expressão cron de 5 partes, ou descreve um momento que nunca chega (como 31 de fevereiro).

O que fazer: escreva minuto, hora, dia do mês, mês e dia da semana, como 0 9 * * 1 para segundas-feiras às 09:00. Veja Agendamento.

invalid_timezone#

HTTP 400. schedule.timezone não é o nome de um fuso horário IANA.

O que fazer: use um nome como Asia/Kolkata, Europe/London ou America/New_York, não uma abreviação como IST nem um deslocamento como +05:30. Veja a referência de fusos horários.

number_not_connected#

HTTP 422. O from do lembrete não é um número conectado deste espaço de trabalho.

O que fazer: conecte o número primeiro, escolha um conectado ou deixe from de fora (null) para que qualquer número conectado envie.

reminder_not_found#

HTTP 404. Nenhum lembrete com este id: ele não existe, foi excluído ou é enviado por um número que a chave não pode usar.

O que fazer: confira o id com Listar lembretes.

Mídia#

file_too_large#

HTTP 413. O arquivo enviado tem mais de 64 MB.

O que fazer: comprima-o ou divida-o; no caso de um vídeo, diminua a resolução.

unsupported_file_type#

HTTP 415. O tipo do arquivo não pode ser enviado pelo WhatsApp. O tipo é lido pela extensão no final do nome do arquivo.

O que fazer: confira os tipos que você pode enviar e mantenha a extensão no nome (price-list.pdf, não price-list).

storage_full#

HTTP 422. O arquivo não cabe no Diretório de mídia do espaço de trabalho para o plano dele. used e limit dizem quanto está em uso e quanto é permitido, em bytes.

O que fazer: exclua arquivos de que você não precisa mais ou passe para um plano com mais armazenamento.

media_in_use#

HTTP 409. O arquivo ainda não pode ser excluído: algo ainda vai enviá-lo (uma mensagem em espera, inclusive de uma campanha, um lembrete ativo ou um gatilho ativo do Google Sheets). count diz quantos.

O que fazer: cancele ou altere esses itens primeiro, ou espere até que as mensagens em espera tenham saído.

upload_failed#

HTTP 502. O arquivo não pôde ser armazenado do nosso lado.

O que fazer: tente de novo, com a mesma Idempotency-Key.

Verificação de números#

no_valid_numbers#

HTTP 422. Nenhuma das entradas em numbers é um número de telefone. skipped diz quantas entradas havia.

O que fazer: envie números em formato internacional com +, um por entrada, como +919876543210.

too_many_numbers#

HTTP 422. A verificação tem mais números do que uma verificação pode ter: mais de 10.000 entradas na requisição, ou mais números do que o plano permite por verificação. count e limit dizem quantos.

O que fazer: divida a lista em várias verificações. Veja Limites do plano.

number_check_quota_reached#

HTTP 422. A verificação ultrapassaria as verificações de números do plano neste período de cobrança. requested, used e limit dizem quantos.

O que fazer: verifique menos números, espere o próximo período de cobrança ou faça upgrade do plano.

number_check_not_found#

HTTP 404. Nenhuma verificação de números com este id no espaço de trabalho.

O que fazer: confira o id com Listar verificações.

Números#

plan_required#

HTTP 403. O plano do espaço de trabalho não inclui o que esta requisição precisa: a API de código QR para conectar um número, lembretes para criar, alterar ou retomar um lembrete, ou a verificação de números para iniciar uma verificação de números.

O que fazer: um Proprietário pode fazer upgrade em Preços. Ler o que já existe funciona em qualquer plano.

number_limit_reached#

HTTP 403. O plano não tem espaço para mais um número.

O que fazer: reconecte um número existente com number_id, remova um número que você não usa mais ou faça upgrade do plano.

already_connected#

HTTP 409. O número já está conectado.

O que fazer: nada a fazer: você pode enviar por ele. Confira com Obter um número.

connect_in_progress#

HTTP 409. Este número está sendo conectado neste momento. number_id no erro diz qual.

O que fazer: consulte periodicamente GET /numbers/{id} para esse número em vez de pedir de novo. Depois de 10 minutos sem leitura do código, você pode pedir de novo.

Webhooks#

invalid_webhook_url#

HTTP 422. url não é um endereço público https://: é http://, está malformado ou aponta para um endereço privado ou local.

O que fazer: use um endereço https:// em que o seu servidor responda pela internet. Para testar no seu computador, use um serviço de túnel que forneça um endereço público https://.

webhook_limit_reached#

HTTP 403. O espaço de trabalho já tem 5 endpoints de webhook.

O que fazer: remova um que você não usa mais. Um único endpoint pode receber todos os tipos de evento.

webhook_not_found#

HTTP 404. Nenhum endpoint de webhook com este id: ele não existe ou foi removido. Testar ou trocar o segredo de um endpoint que parou também responde isso; lê-lo mostra active: false.

O que fazer: confira o id com Listar endpoints. Se ele parou, adicione-o de novo.

Modo de teste#

test_mode_unsupported#

HTTP 403. Uma chave de teste (wbz_test_…) pode enviar, ler e cancelar mensagens de teste e ler o resto do espaço de trabalho, mas não alterar mais nada: conectar um número, criar, alterar ou excluir lembretes, enviar ou excluir mídia, iniciar uma verificação de números ou gerenciar endpoints de webhook. O filtro status de GET /messages também não é aceito para chaves de teste.

O que fazer: use uma chave real (wbz_live_…) para essas requisições. Veja Modo de teste.