Erros
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 HTTP | Descrição |
|---|---|
400 | O 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. |
401 | A chave está ausente, malformada, inexistente, expirada ou revogada. O corpo é sempre o mesmo, sem dizer qual. |
403 | A 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. |
404 | O recurso não existe, ou não é seu. As duas respostas são idênticas, byte a byte. |
409 | O pedido está bem formado, mas o estado do recurso não o admite. O campo error diz qual é o caso. |
410 | O link de conexão venceu ou já foi usado. O campo error diz qual dos dois. |
413 | O arquivo passa do teto de tamanho, que é o mesmo para todos os clientes. |
415 | O corpo veio com um content-type que a rota não lê. Envie application/json, ou multipart/form-data nas rotas de arquivo. |
422 | O 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. |
429 | Requisiçõ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. |
503 | A 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 HTTP | Quando acontece | Rotas |
|---|---|---|---|
invalid_request | 400 | Campo recusado, com o motivo | 73 |
invalid_reset_token | 400 | Link de redefinição inválido | 2 |
unauthorized | 401 | Chave recusada | 77 |
account_blocked | 403 | Conta bloqueada pela Helsen | 25 |
connection_not_released | 403 | Conta ainda sem liberação para conectar | 4 |
forbidden | 403 | Escopo insuficiente | 76 |
test_key_not_allowed | 403 | Chave de teste numa rota que não é do modo de teste | 74 |
trial_expired | 403 | Teste grátis terminado | 25 |
not_found | 404 | Não existe, ou não é seu | 49 |
account_at_capacity | 409 | A conta que pediu o link atingiu o máximo de números | 1 |
already_requeued | 409 | Item já re-enfileirado | 1 |
idempotency_key_reused | 409 | Idempotency-Key usada com outro corpo | 1 |
link_not_open | 409 | Link que não está aberto | 1 |
media_not_ready | 409 | Mídia ainda não obtida | 2 |
message_not_cancelable | 409 | Mensagem que já saiu da fila | 1 |
no_webhook_endpoint | 409 | Sem endpoint de webhook ativo | 1 |
not_available_in_coexistence | 409 | Indisponível em coexistência | 2 |
number_capacity_reached | 409 | A conta já está na capacidade de números | 4 |
number_disconnected | 409 | Número desconectado da Luna | 10 |
pin_not_applicable | 409 | O número não pede PIN | 1 |
reconnect_not_applicable | 409 | A autorização não admite reconexão | 2 |
register_budget_reserved | 409 | Tentativas de registro reservadas | 1 |
template_content_unknown | 409 | A Luna não conhece o conteúdo do template | 1 |
template_not_approved | 409 | Template que ainda não está aprovado | 1 |
webhook_endpoint_limit | 409 | Limite de endpoints | 1 |
window_closed | 409 | Janela de atendimento fechada | 1 |
link_expired | 410 | Link vencido | 1 |
link_used | 410 | Link já usado | 2 |
file_too_large | 413 | Arquivo acima do teto | 2 |
unsupported_media_type | 415 | Tipo de conteúdo não lido | 33 |
meta_rejected | 422 | A Meta recusou a operação | 9 |
management_busy | 429 | Gestão da conta ocupada | 14 |
number_rate_limited | 429 | Ritmo do número | 2 |
queue_full | 429 | Fila de envio cheia | 1 |
rate_limited | 429 | Limite de requisições | 88 |
unavailable | 503 | Indisponível | 88 |