Erros

A API do FlowMail utiliza códigos de status HTTP convencionais para indicar o sucesso ou a falha de uma requisição. Todas as respostas de erro seguem um formato JSON padronizado para facilitar o tratamento no seu código.

Formato de Erro

Todas as respostas de erro retornam um objeto JSON com os campos error e message. Em erros de validação (422), o campo details também está presente.

FORMATO PADRÃO
{
  "error": "codigo_do_erro",
  "message": "Descrição legível do erro."
}
FORMATO COM DETALHES (422)
{
  "error": "validation_error",
  "message": "Os dados enviados são inválidos.",
  "details": {
    "email": ["O campo e-mail deve ser um endereço válido."],
    "webhook_url": ["A URL deve usar o protocolo HTTPS."]
  }
}

Códigos de Status HTTP

Abaixo estão todos os códigos de status que a API pode retornar, com suas respectivas descrições e cenários de uso.

Código Status Erro Descrição
400 Bad Request bad_request A requisição está malformada ou possui parâmetros inválidos.
401 Unauthorized unauthorized API key ausente, inválida ou expirada.
403 Forbidden forbidden Sua API key não tem permissão para acessar este recurso ou sua cota mensal foi excedida.
404 Not Found not_found O recurso solicitado não existe. Verifique a URL e os identificadores.
409 Conflict conflict Conflito com o estado atual do recurso (ex: job em lote já em processamento).
422 Unprocessable Entity validation_error Os dados enviados falharam na validação. Veja o campo details para os erros específicos.
429 Too Many Requests rate_limit_exceeded Limite de requisições por segundo excedido. Consulte a página de Rate Limits.
500 Internal Server Error internal_error Erro interno do servidor. Se persistir, entre em contato com o suporte.
503 Service Unavailable service_unavailable Serviço temporariamente indisponível por manutenção. Tente novamente em alguns minutos.

Exemplos de Erros Comuns

API key inválida

401 UNAUTHORIZED
{
  "error": "unauthorized",
  "message": "API key inválida ou expirada. Verifique suas credenciais no dashboard."
}

E-mail com formato inválido

422 UNPROCESSABLE ENTITY
{
  "error": "validation_error",
  "message": "Os dados enviados são inválidos.",
  "details": {
    "email": ["O formato do e-mail informado é inválido."]
  }
}

Cota mensal excedida

403 FORBIDDEN
{
  "error": "forbidden",
  "message": "Cota mensal de verificações excedida. Faça upgrade do seu plano ou aguarde a renovação."
}

Lote com muitos e-mails

400 BAD REQUEST
{
  "error": "bad_request",
  "message": "O lote excede o limite máximo de 10.000 e-mails por requisição."
}

Boas Práticas de Tratamento de Erros

Sempre verifique o código HTTP

Não confie apenas no corpo da resposta. Verifique o código de status HTTP primeiro. Códigos 2xx indicam sucesso, 4xx indicam erro do cliente e 5xx indicam erro do servidor.

Trate erros de forma granular

Use o campo error para tratar cada tipo de erro programaticamente. Mostre o campo message apenas para o usuário final.

Retente apenas erros recuperáveis

Erros 429, 500 e 503 podem ser retentados com backoff exponencial. Erros 400, 401, 403 e 422 não devem ser retentados sem corrigir a requisição.

Registre os erros com contexto

Ao registrar erros, inclua o código de status, o corpo da resposta e o ID da requisição (header X-Request-Id) para facilitar a depuração junto ao suporte.