Erros

Toda resposta de erro segue o mesmo formato:

{
  "error": {
    "code": "outside_24h_window",
    "message": "A janela de 24 horas desta conversa está fechada. Envie com um template aprovado (fallback_template).",
    "details": { "approved_templates": [] },
    "docs_url": "https://docs.konversia.com.br/api/erros/outside_24h_window"
  }
}

Ramifique sempre em error.code, nunca em error.message: a mensagem pode mudar de texto, o código não. error.details varia por código, ver a coluna "O que aconteceu" na tabela abaixo; quando não há detalhe extra, vem como objeto vazio.

Tabela completa

Código	Status HTTP	O que aconteceu	O que fazer
unauthenticated	401	Cabeçalho Authorization ausente, ou chave inválida/revogada	Conferir o cabeçalho; se a chave foi revogada, gerar uma nova
forbidden_scope	403	A chave não tem o escopo exigido pelo endpoint (error.details.required_scope)	Pedir ao dono da empresa uma chave, ou um escopo, com essa permissão
subscription_inactive	403	Assinatura da empresa inativa, ou com pagamento pendente	Aguardar a regularização do pagamento; a chave continua a mesma
rate_limited	429	Mais de 120 requisições por minuto para esta chave	Esperar e repetir, com um intervalo crescente entre tentativas
quota_exceeded	429	Cota mensal de envios da empresa atingida	Falar com o suporte para aumentar o limite, ou esperar o próximo mês
circuit_open	429	Envio automático pausado por volume anormal na última hora	Esperar; a pausa se desfaz sozinha
request_in_progress	409	Outra chamada com a mesma Idempotency-Key ainda está sendo processada	Esperar alguns segundos e repetir
idempotency_key_reused	409	A mesma Idempotency-Key chegou com um corpo diferente do da primeira vez	Usar uma chave nova para um pedido de negócio diferente
validation_failed	422	Corpo da requisição inválido: campo ausente, formato errado, ou Idempotency-Key faltando	Corrigir os campos apontados em error.details
invalid_phone_number	422	O campo to não é um telefone reconhecível	Conferir o formato do telefone
contact_blocked	422	O contato de destino está bloqueado	Desbloquear na tela, se fizer sentido para o caso
channel_not_found	422	Não foi possível determinar o canal: channel_id inexistente, ou nenhum/mais de um canal utilizável sem um channel_id explícito	Informar um channel_id de error.details.available_channels
channel_disconnected	400	O canal existe, mas não está conectado no momento	Reconectar o canal na tela, ou usar outro
channel_without_default_department	422	O canal não tem um setor padrão configurado	Configurar um setor padrão para o canal na tela
file_not_found	404	file_id inexistente, ou pertencente a outra empresa	Subir o arquivo de novo e usar o id devolvido
media_too_large	413	Arquivo maior que 15 MB	Reduzir o arquivo antes de subir
unsupported_media_type	415	Tipo de arquivo fora da lista aceita (error.details.detected_mime)	Usar um dos tipos aceitos, ver Enviar mídia
outside_24h_window	422	Janela de 24 horas fechada e nenhum fallback_template informado (error.details.approved_templates traz as opções)	Reenviar com fallback_template, ou usar POST /v1/messages/template
media_requires_active_window	422	Mídia fora da janela de 24 horas: o fallback substituiria o anexo por um template de texto	Enviar dentro da janela, ou trocar para POST /v1/messages/text
template_not_approved	422	O template não existe, ou não está aprovado no canal resolvido para este envio	Conferir nome, idioma e canal em GET /v1/templates
template_requires_header_media	422	O template exige um arquivo de cabeçalho (imagem, vídeo ou documento) escolhido a cada envio, e a API ainda não tem campo para informá-lo	Usar um template sem cabeçalho de mídia dinâmica, ou com cabeçalho de mídia fixa
template_variables_mismatch	422	Quantidade de variables diferente da exigida pelo template (error.details.expected/received)	Ajustar a quantidade de variáveis enviada
not_found	404	Recurso não encontrado: rota inexistente, ou um id totalmente desconhecido	Conferir a URL ou o id usado
server_error	500	Erro interno do Konversia	Tentar de novo mais tarde; se persistir, falar com o suporte informando o horário

Relacionado

• Enviar mensagens
• Autenticação