Docs/Tratamento de Erros

Tratamento de Erros

Todos os erros da API seguem um formato consistente. Veja como tratá-los sem dor de cabeça.

Ver Markdown OpenAPI JSON

Formato da resposta de erro

Quando ocorre um erro, a API retorna um objeto JSON com esta estrutura:

json
{
  "error": "Validation Error",
  "message": "The email field is required.",
  "status_code": 422
}

Códigos de erro

Código de statusErroCausa e solução
400 Requisição inválida JSON malformado ou campos obrigatórios ausentes. Confira o corpo da sua requisição.
401 Não autorizado Chave de API ausente ou inválida. Confira o seu Authorization cabeçalho.
402 Pagamento necessário Créditos insuficientes. Compre mais créditos ou aguarde o limite diário ser renovado.
422 Erro de validação O formato do endereço de e-mail é inválido. Confira o valor que você está enviando.
429 Requisições demais Limite de requisições excedido. Confira o Retry-After cabeçalho e aguarde.
500 Erro interno do servidor Algo deu errado do nosso lado. Tente de novo em alguns segundos. Fale com o suporte se continuar falhando.

401 Não autorizado

json
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key",
  "status_code": 401
}

Correção: Confira se o seu Authorization cabeçalho está formatado corretamente como Bearer YOUR_API_KEY. Verifique sua chave no painel.

422 Erro de validação

json
{
  "error": "Validation Error",
  "message": "The email field must be a valid email address.",
  "status_code": 422
}

Correção: Garanta que o valor do e-mail tenha um formato válido (ex.: user@example.com). Limpe os dados de entrada antes de enviar.

429 Requisições demais

json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please slow down.",
  "status_code": 429,
  "retry_after": 15
}

Correção: Aguarde o número de segundos indicado em retry_after antes de tentar de novo. Veja Limites de requisição →

Checklist de solução de problemas