Códigos de Erro
Referência completa dos códigos HTTP e formato de resposta de erro.
Formato Padrão de Erro
Todas as respostas de erro seguem o formato ApiErrorResponse:
{
"status": 400,
"error": "Bad Request",
"message": "Telefone é obrigatório",
"timestamp": "2024-04-11T10:30:00"
}
| Campo | Tipo | Descrição |
|---|---|---|
status | integer | Código HTTP da resposta |
error | string | Tipo do erro (derivado do status) |
message | string | Descrição detalhada do erro |
timestamp | string | Data/hora do erro (ISO 8601) |
Códigos HTTP
| Código | Tipo | Descrição | Exemplo |
|---|---|---|---|
400 | Bad Request | Dados inválidos ou ausentes | Campo obrigatório não preenchido |
401 | Unauthorized | Credenciais inválidas | API Key incorreta ou JWT expirado |
402 | Payment Required | Saldo insuficiente | Aplicação sem créditos para envio |
403 | Forbidden | Acesso negado | Usuário sem permissão para o recurso |
404 | Not Found | Recurso não encontrado | Mensagem ou aplicação inexistente |
500 | Internal Server Error | Erro interno do servidor | Falha na comunicação com Twilio |
Erros de Validação (400)
Erros de validação de campos retornam a mensagem específica do campo inválido:
{
"status": 400,
"error": "Bad Request",
"message": "Telefone é obrigatório",
"timestamp": "2024-04-11T10:30:00"
}
Validações comuns:
"Telefone é obrigatório"— campo telefone ausente ou vazio"Mensagem é obrigatória"— campo mensagem ausente ou vazio- Formato de telefone inválido — deve incluir DDI (ex:
+5511999999999)
Erro de Saldo Insuficiente (402)
Retornado ao tentar enviar mensagem sem saldo suficiente. Formato especial:
{
"error": "Saldo insuficiente",
"message": "A aplicação não possui saldo suficiente para enviar mensagens.",
"saldo": "0.00"
}
Adicione créditos via painel administrativo antes de enviar mensagens.
Erros do Twilio
Erros do Twilio são capturados nos callbacks de status e registrados nos campos errorCode e errorMessage da mensagem. Códigos comuns:
| Código | Descrição |
|---|---|
21211 | Número de telefone inválido |
21408 | Permissão negada para enviar ao número |
21610 | Destinatário optou por não receber mensagens (opt-out) |
63016 | Número não registrado no WhatsApp |
63032 | Conta sandbox — destinatário precisa aceitar sandbox |
Importante: Erros do Twilio não geram resposta de erro na API de envio. Eles são registrados assincronamente quando o Twilio envia o callback de status para o endpoint de webhook.