Erros

Todo erro vem em application/problem+json (RFC 9457):

{
  "type": "https://docs.recadu.com.br/problems/contact-opted-out",
  "title": "Dados inválidos",
  "status": 422,
  "detail": "Este contato pediu para não receber mais mensagens desta conta. ...",
  "instance": "/v1/messages",
  "request_id": "5f0c9a1e2b7d4c8e9a6b3d2f1e0c4b7a"
}

• Trate pelo type: ele não muda. O detail é para pessoas e pode mudar.
• Alguns erros trazem campos a mais, como errors (validação) e required_scope.
• Ao falar com o suporte, mande o request_id.

Vale tentar de novo? Sim em 429 (depois do Retry-After), 500, 502 e 503, sempre com a mesma Idempotency-Key. Nos outros, corrija o pedido antes.

Falhas depois que a mensagem foi aceita (número sem WhatsApp, mídia que não baixa) não são erros HTTP: aparecem em error.code da mensagem e no evento message.failed. Veja mensagens.

Autenticação e permissão

unauthorized

401. Falta a chave, ou ela é inválida ou foi revogada. Mande Authorization: Bearer gwk_live_....

insufficient-scope

403. A chave não tem o escopo da operação (vem em required_scope). Crie uma chave com o escopo no painel.

forbidden

403. O seu papel no painel não permite a ação.

account-suspended

403. A conta está suspensa e os envios estão bloqueados. Fale com o suporte.

Pedido

validation-error

422. Campos inválidos; a lista está em errors, com o caminho de cada campo.

invalid-message

422. A mensagem não está montada certo: por exemplo, type: "image" sem o campo image, ou um botão url sem url. O detail diz o quê.

invalid-phone

422. Telefone com DDI e DDD, só dígitos, de 8 a 15.

invalid-reply-to

422. A mensagem citada em reply_to não existe nesta instância ou ainda não saiu.

invalid-policy

422. Política com valor inválido (horário fora do formato HH:MM, número negativo...).

invalid-timezone

422. Fuso desconhecido. Use nomes IANA, como America/Sao_Paulo.

invalid-month

422. Use o mês como AAAA-MM.

invalid-webhook-url

422. A URL do webhook precisa ser HTTPS e apontar para um endereço público.

invalid-cursor

400. O cursor da paginação é inválido ou venceu. Comece de novo sem cursor.

invalid-idempotency-key

400. Idempotency-Key deve ter de 1 a 255 caracteres.

idempotency-key-reused

422. A mesma Idempotency-Key foi usada com outro corpo nas últimas 24 h. Gere uma chave por envio.

idempotency-in-progress

409. Um pedido com esta Idempotency-Key ainda está sendo processado. Espere um pouco e repita.

precondition-failed

412. O recurso mudou desde que você o leu (If-Match não confere). Leia de novo e reaplique a mudança.

not-found

404. O recurso não existe nesta conta, ou a chave é restrita a outras instâncias.

method-not-allowed

405. Método HTTP não aceito nesta rota.

Instâncias

instance-limit-reached

409. O plano não permite mais instâncias. Remova uma ou fale com o suporte para mudar o plano.

instance-name-taken

409. Já existe uma instância com este nome na conta.

sandbox-limit-reached

409. Cada conta pode ter até 3 instâncias sandbox.

not-sandbox

409. Só instâncias sandbox aceitam mensagens simuladas.

already-paired

409. A instância já está pareada. Desconecte (POST .../logout) antes de parear de novo.

pairing-failed

502. O WhatsApp recusou o pareamento. Para o código, confira o telefone; tente de novo em seguida.

engine-unavailable

503. A conexão com o WhatsApp não respondeu a tempo. Tente de novo em alguns segundos (Retry-After).

Envio

contact-opted-out

422. O contato pediu para não receber mais mensagens (mandou SAIR). Ele volta a receber se mandar VOLTAR. Remover o descadastro pela API (DELETE /v1/opt-outs/{phone}) só com o consentimento dele. Veja descadastro.

policy-new-contacts-limit

429. A instância chegou ao limite de contatos novos (quem nunca escreveu) nas últimas 24 h. Espere o Retry-After ou reduza os envios ativos. Número em aquecimento tem limite menor. Veja políticas.

policy-mass-send-blocked

422. O mesmo texto foi para muitos contatos novos em pouco tempo, o que parece disparo em massa. Personalize a mensagem (nome, pedido) ou espalhe os envios.

policy-outside-hours

422. Mensagem para quem não escreveu nas últimas 24 h, fora da janela de horário da instância. Mande dentro da janela ou use active_hours.outside: "schedule" para agendar. Veja janela de horário.

rate-limited

429. Passou do limite de requisições por minuto da chave. Espere o Retry-After.

media-not-found

422. O media_id não existe ou já venceu (30 dias). Envie o arquivo de novo.

media-expired

410. O arquivo venceu e não pode mais ser usado nem baixado.

file-too-large

413. O arquivo passa de 64 MB.

empty-file

422. O arquivo enviado está vazio.

Mensagens enviadas

message-not-sent

409. A mensagem ainda não saiu, então não dá para editar, apagar para todos ou reagir.

not-editable

409. Só mensagens de texto podem ser editadas.

edit-window-closed

409. O WhatsApp só permite editar até 15 minutos depois do envio.

message-sending

409. A mensagem já está saindo e não dá mais para cancelar.

Webhooks

webhook-limit-reached

409. A conta já tem 10 destinos de webhook.

delivery-pending

409. A entrega ainda está em andamento; espere ela terminar para reenviar.

Erros do servidor

internal-error

500. Erro inesperado do Recadu. Tente de novo; se repetir, mande o request_id ao suporte.

Painel

Erros que aparecem no painel, não na API com chave.

invalid-credentials

401 ou 422. E-mail ou senha incorretos.

login-locked

429. Muitas tentativas erradas; espere os minutos indicados.

mfa-required

401. Conclua a verificação em duas etapas (2FA).

invalid-code

422. Código do 2FA incorreto. Confira se o horário do celular está automático.

mfa-not-pending, mfa-not-verified, mfa-setup-not-started

409. Passo do 2FA fora de ordem. Recarregue a página e comece de novo.

weak-password

422. A senha precisa de pelo menos 12 caracteres, não pode ser o e-mail nem repetitiva demais (como aaaaaaaaaaaa).

csrf-failed

403. A sessão da página venceu. Recarregue.

origin-not-allowed

403. Pedido vindo de outro site. Entre pelo endereço do painel.

no-account

403. O seu usuário não participa (ou deixou de participar) de nenhuma conta.

invitation-invalid

404. Convite vencido ou já usado. Peça outro ao dono da conta.

already-member, user-exists

409. O e-mail já participa da conta / já tem usuário.

last-owner

409. A conta precisa de pelo menos um dono.

invalid-scopes

422. Escolha pelo menos um escopo válido para a chave.

invalid-expiration

422. A validade da chave precisa ser no futuro.

contact-exists, too-many-contacts, invalid-contact

409 / 422. Contatos de aviso de desconexão: já cadastrado, limite atingido ou dado inválido.

handoff-invalid

401. Link de acesso do suporte vencido ou já usado.