Estrutura de Erro
Todas as respostas de erro seguem o mesmo formato:| Campo | Tipo | Descrição |
|---|---|---|
statusCode | number | Código HTTP do erro |
error | string | Código identificador do erro |
message | string | Mensagem legível descrevendo o erro |
details | object | Informações adicionais (opcional) |
timestamp | string | Data/hora do erro (ISO 8601) |
path | string | Endpoint que gerou o erro |
Códigos HTTP
- 2xx Sucesso
- 4xx Erro do Cliente
- 5xx Erro do Servidor
| Código | Significado |
|---|---|
| 200 | OK - Requisição bem sucedida |
| 201 | Created - Recurso criado com sucesso |
| 204 | No Content - Sucesso sem corpo de resposta |
Códigos de Erro
Autenticação
| Código | HTTP | Descrição |
|---|---|---|
UNAUTHORIZED | 401 | API Key ausente ou inválida |
API_KEY_REVOKED | 403 | API Key foi revogada |
INSUFFICIENT_PERMISSIONS | 403 | Sem permissão para o recurso |
Validação
| Código | HTTP | Descrição |
|---|---|---|
VALIDATION_ERROR | 400 | Dados de entrada inválidos |
INVALID_PHONE_FORMAT | 400 | Formato de telefone inválido |
INVALID_JID_FORMAT | 400 | Formato de JID inválido |
MISSING_REQUIRED_FIELD | 400 | Campo obrigatório ausente |
Sessões
| Código | HTTP | Descrição |
|---|---|---|
SESSION_NOT_FOUND | 404 | Sessão não existe |
SESSION_ALREADY_EXISTS | 409 | Sessão com mesmo nome já existe |
SESSION_NOT_CONNECTED | 400 | Sessão não está conectada |
SESSION_LIMIT_REACHED | 403 | Limite de sessões do plano atingido |
SESSION_CREATION_FAILED | 500 | Falha ao criar sessão |
Mensagens
| Código | HTTP | Descrição |
|---|---|---|
MESSAGE_SEND_FAILED | 500 | Falha ao enviar mensagem |
MESSAGE_LIMIT_REACHED | 403 | Limite de mensagens do plano atingido |
RECIPIENT_NOT_ON_WHATSAPP | 400 | Destinatário não usa WhatsApp |
MEDIA_TOO_LARGE | 400 | Arquivo excede o limite de tamanho |
UNSUPPORTED_MEDIA_TYPE | 400 | Tipo de mídia não suportado |
Grupos
| Código | HTTP | Descrição |
|---|---|---|
GROUP_NOT_FOUND | 404 | Grupo não existe |
NOT_GROUP_ADMIN | 403 | Não é administrador do grupo |
PARTICIPANT_ALREADY_EXISTS | 409 | Participante já está no grupo |
PARTICIPANT_NOT_FOUND | 404 | Participante não encontrado |
Contatos
| Código | HTTP | Descrição |
|---|---|---|
CONTACT_NOT_FOUND | 404 | Contato não encontrado |
NUMBER_NOT_ON_WHATSAPP | 400 | Número não está no WhatsApp |
Rate Limiting
| Código | HTTP | Descrição |
|---|---|---|
TOO_MANY_REQUESTS | 429 | Rate limit excedido |
WHATSAPP_RATE_LIMIT | 429 | Rate limit do WhatsApp |
Webhooks
| Código | HTTP | Descrição |
|---|---|---|
WEBHOOK_NOT_FOUND | 404 | Webhook não encontrado |
WEBHOOK_URL_UNREACHABLE | 400 | URL do webhook não acessível |
WEBHOOK_LIMIT_REACHED | 403 | Limite de webhooks do plano |
Tratamento de Erros
Exemplo em TypeScript
Exemplo em Python
Boas Práticas
Sempre trate erros específicos
Sempre trate erros específicos
Não use apenas
catch genérico. Trate cada tipo de erro de forma adequada para melhor experiência do usuário.Implemente retry com backoff
Implemente retry com backoff
Para erros 5xx e 429, implemente retry automático com exponential backoff.
Log erros para debugging
Log erros para debugging
Salve logs detalhados de erros incluindo timestamp, path, e details para facilitar troubleshooting.
Monitore taxa de erros
Monitore taxa de erros
Configure alertas quando a taxa de erros 4xx ou 5xx ultrapassar um threshold.