LunaDocs

Carregando a busca...

EnglishEntrar no console
Nesta página

Erros

Usar com IA

Todo erro da API tem o mesmo formato. Decida pelo status HTTP e pelo código em error: os dois são estáveis. O texto de message é para uma pessoa ler e pode mudar.

O corpo é { "error": "codigo", "message": "texto" }, e alguns erros trazem campos a mais que dizem o que fazer. A recusa de validação (400, invalid_request) traz campos: uma lista em que cada item tem o campo recusado e o motivo. O valor que você enviou nunca volta na resposta.

404 também é usado para um recurso que existe e não é seu: a API não confirma a existência de recurso de outro cliente, nem pelo status.

O guia Erros explica o que fazer em cada caso, com código para repetir em 429 e 503.

Por status HTTP#

Status HTTPDescrição
400O corpo, a query ou o identificador não bate com o contrato. Cada item de campos diz o campo e o motivo, e o valor enviado nunca volta. Repetir o mesmo pedido repete a recusa.
401A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual.
403A chave não tem o escopo que a rota exige. Em rota que abre conexão de número, também quando a conta ainda não pode conectar (connection_not_released). Nas rotas que escrevem ou enviam, também quando a conta está suspensa: trial_expired (o teste grátis terminou) ou account_blocked (a Helsen bloqueou a conta). A suspensão não toca o recebimento: o que chega continua sendo entregue ao seu webhook. Uma chave de teste (mode test) só usa POST /v1/messages e POST /v1/test-mode/inbound-messages; nas demais rotas recebe test_key_not_allowed.
404O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte.
409O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso.
410O link de conexão venceu ou já foi usado. O campo error diz qual dos dois.
413O arquivo passa do teto de tamanho, que é o mesmo para todos os clientes.
415O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo.
422O pedido está bem formado e a Luna o repassou, e a Meta recusou. O campo meta traz o que aconteceu, o que fazer e o erro original dela. Repetir o mesmo pedido repete a recusa.
429Requisições demais, ou uma fila cheia. Espere o tempo do cabeçalho Retry-After e repita. Para POST /v1/messages, repita com o mesmo Idempotency-Key.
503A plataforma não está em condições de atender agora. Repita depois de alguns instantes, com o mesmo Idempotency-Key quando houver.

Por código de erro#

Código do erro (error)Status HTTPQuando aconteceRotas
invalid_request400Campo recusado, com o motivo73
invalid_reset_token400Link de redefinição inválido2
unauthorized401Chave recusada77
account_blocked403Conta bloqueada pela Helsen25
connection_not_released403Conta ainda sem liberação para conectar4
forbidden403Escopo insuficiente76
test_key_not_allowed403Chave de teste numa rota que não é do modo de teste74
trial_expired403Teste grátis terminado25
not_found404Não existe, ou não é seu49
account_at_capacity409A conta que pediu o link atingiu o máximo de números1
already_requeued409Item já re-enfileirado1
idempotency_key_reused409Idempotency-Key usada com outro corpo1
link_not_open409Link que não está aberto1
media_not_ready409Mídia ainda não obtida2
message_not_cancelable409Mensagem que já saiu da fila1
no_webhook_endpoint409Sem endpoint de webhook ativo1
not_available_in_coexistence409Indisponível em coexistência2
number_capacity_reached409A conta já está na capacidade de números4
number_disconnected409Número desconectado da Luna10
pin_not_applicable409O número não pede PIN1
reconnect_not_applicable409A autorização não admite reconexão2
register_budget_reserved409Tentativas de registro reservadas1
template_content_unknown409A Luna não conhece o conteúdo do template1
template_not_approved409Template que ainda não está aprovado1
webhook_endpoint_limit409Limite de endpoints1
window_closed409Janela de atendimento fechada1
link_expired410Link vencido1
link_used410Link já usado2
file_too_large413Arquivo acima do teto2
unsupported_media_type415Tipo de conteúdo não lido33
meta_rejected422A Meta recusou a operação9
management_busy429Gestão da conta ocupada14
number_rate_limited429Ritmo do número2
queue_full429Fila de envio cheia1
rate_limited429Limite de requisições88
unavailable503Indisponível88