Erros

A API do Emailit usa códigos de status HTTP para informar se uma requisição funcionou. Códigos na faixa 2xx indicam sucesso, códigos 4xx indicam que algo na requisição precisa mudar, e códigos 5xx indicam que algo deu errado do nosso lado. Esta página descreve os corpos de erro, todos os códigos de status que a API retorna e como corrigir os erros mais comuns.

Formatos de resposta de erro

Todo corpo de erro é um objeto JSON com um campo error. O formato exato depende de onde a requisição falhou. Escreva o seu tratamento de erros para ler error, depois message quando estiver presente, e depois quaisquer campos extras que o endpoint documente.

Erros de requisição

Falhas de autenticação, erros de permissão, JSON malformado e outros erros gerados antes de um endpoint ser executado usam o formato de erro HTTP padrão:

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "API key required"
}

Erros de validação

Quando um parâmetro de consulta ou um campo do corpo tem o tipo errado, está ausente ou está fora do intervalo permitido, a API rejeita a requisição com 400 antes de executá-la e lista cada problema em details:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation error",
  "details": [
    {
      "instancePath": "/limit",
      "schemaPath": "#/properties/limit/maximum",
      "keyword": "maximum",
      "params": { "comparison": "<=", "limit": 100 },
      "message": "must be <= 100"
    }
  ]
}

instancePath aponta para o campo (/limit, /to, /attachments/0/filename), e message descreve a regra violada. Em alguns endpoints, como Enviar um e-mail, esses erros retornam apenas {"error": "Bad Request"}.

Erros de recurso

Erros gerados por um endpoint, como um objeto inexistente ou um nome duplicado, retornam error e muitas vezes message:

{
  "error": "Email not found",
  "message": "Email with ID 'em_4KYof1ZzXndZE2VPi0DgULiekG8' not found in your workspace"
}

Alguns erros adicionam campos que ajudam você a se recuperar:

Erros de validação de envio

Enviar um e-mail e Encaminhar um e-mail verificam a mensagem inteira de uma vez e retornam todos os problemas em validation_errors:

{
  "error": "Validation failed",
  "validation_errors": [
    "Missing required field: subject",
    "Invalid to email address at index 1: ada@example"
  ]
}

Erros por campo

Templates, campanhas e automações retornam os problemas de validação agrupados por campo:

{
  "message": "Validation failed",
  "errors": {
    "alias": ["Alias must contain only lowercase letters (a-z), numbers (0-9), underscores (_), and hyphens (-)"]
  }
}

Erros de limite de requisições

As respostas 429 dos endpoints de envio incluem o limite atingido e quanto tempo esperar. Consulte Limites de requisições.

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Maximum 2 messages per second allowed.",
  "limit": 2,
  "current": 2,
  "retry_after": 1
}

Códigos de status HTTP

Erros comuns e como corrigi-los

Tentar de novo com segurança

• Tente de novo as respostas 429, 500 e 503 depois de um intervalo. Use o cabeçalho retry-after quando ele estiver presente e, caso contrário, backoff exponencial. Limites de requisições tem código de exemplo.
• Não repita sem alterações as requisições com outros erros 4xx. Elas falham da mesma forma até você corrigir a requisição.
• Ao tentar enviar de novo depois de um timeout ou de um erro 5xx, reutilize o mesmo Idempotency-Key para que o e-mail não seja enviado duas vezes.

Veja também