# Erros

> Como a API do Emailit informa erros. Formatos do corpo da resposta, códigos de status HTTP e o que significam, e soluções para as mensagens de erro mais frequentes.

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:

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

| Campo | Descrição |
| --- | --- |
| `statusCode` | O código de status HTTP. |
| `error` | A frase de motivo HTTP, como `Unauthorized` ou `Forbidden`. |
| `message` | O que deu errado, em linguagem simples. |

### 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`:

```json
{
  "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](/pt/docs/api-reference/emails/send/), 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`:

```json
{
  "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:

| Campo | Retornado com | Contém |
| --- | --- | --- |
| `existing` | `409` quando você cria um domínio, uma chave de API, uma lista de contatos, um contato ou um inscrito duplicado | O objeto que já existe, para que você possa usá-lo em vez de criar outro. |
| `usage` | `422` quando um limite do plano é atingido | `used`, `limit` e, para listas de contatos, `plan`. |
| `required_plan` | `403` com `error: "plan_required"` | O plano mais básico que inclui o recurso, como `pro`. |
| `code` | Alguns erros `403` e `422` | Um código estável e legível por máquina, como `unverified_workspace_recipient` ou `events_offset_too_large`. |
| `missing` | `404` de [Atualizar contatos em massa](/pt/docs/api-reference/contacts/bulk/) | Os IDs de contato que não foram encontrados. |

### Erros de validação de envio

[Enviar um e-mail](/pt/docs/api-reference/emails/send/) e [Encaminhar um e-mail](/pt/docs/api-reference/emails/forward/) verificam a mensagem inteira de uma vez e retornam todos os problemas em `validation_errors`:

```json
{
  "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:

```json
{
  "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](/pt/docs/api-reference/rate-limits/).

```json
{
  "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

| Código | Significado | Causas típicas na API do Emailit |
| --- | --- | --- |
| `200` | OK | A requisição funcionou. Envios, atualizações, exclusões e leituras retornam `200`. |
| `201` | Created | Um domínio, uma chave de API, uma lista de contatos, um inscrito, um contato, um template, um webhook ou outro objeto foi criado. |
| `202` | Accepted | O envio de um relatório DMARC foi aceito para processamento. |
| `204` | No Content | Um formulário foi excluído. A resposta não tem corpo. |
| `400` | Bad Request | JSON inválido, um campo obrigatório ausente, um valor do tipo errado ou fora do intervalo, um `Idempotency-Key` inválido ou nenhum campo para atualizar. |
| `401` | Unauthorized | A chave de API está ausente, é inválida, foi excluída ou regenerada, ou um token OAuth expirou. Consulte [Autenticação](/pt/docs/api-reference/authentication/#authentication-errors). |
| `402` | Payment Required | O workspace não tem créditos suficientes para o envio, a nova tentativa ou a verificação. |
| `403` | Forbidden | O escopo da chave não permite o endpoint, uma chave restrita a um domínio enviou de outro domínio, o workspace está suspenso ou ainda não foi verificado, o domínio de envio está pausado, ou o recurso exige um plano superior. |
| `404` | Not Found | O objeto não existe neste workspace, ou um alias de template não tem versão publicada. |
| `409` | Conflict | Já existe um objeto com o mesmo nome ou e-mail, ou uma requisição com o mesmo `Idempotency-Key` ainda está em execução. |
| `413` | Payload Too Large | O e-mail montado tem mais de 40 MB, ou o envio de um relatório DMARC tem mais de 10 MB. |
| `422` | Unprocessable Entity | A requisição é válida, mas não pode ser executada agora: o domínio de `from` não está verificado, um anexo não pôde ser baixado, o status do e-mail não permite cancelar nem tentar de novo, o conteúdo dele já foi apagado, ou um limite do plano foi atingido. |
| `429` | Too Many Requests | O workspace atingiu o limite de envio por segundo ou diário, ou o limite de encaminhamentos por hora. |
| `500` | Internal Server Error | Algo falhou do nosso lado. Tente de novo com backoff e fale com o suporte se o problema persistir. |
| `503` | Service Unavailable | Uma indisponibilidade temporária de uma dependência, como o armazenamento de idempotência ou o banco de dados de autenticação. Tente de novo com backoff. |

## Erros comuns e como corrigi-los

| Status | `error` | Causa | Solução |
| --- | --- | --- | --- |
| `400` | `Validation failed` | Falta `from`, `to`, `subject` ou conteúdo em um envio, ou ele tem um endereço ou anexo inválido. | Corrija cada item listado em `validation_errors`. |
| `400` | `Invalid JSON in request body` (em `message`) | O corpo não é um JSON válido. | Verifique as aspas e as vírgulas finais, e envie `Content-Type: application/json`. |
| `400` | `Invalid Idempotency-Key` | A chave tem mais de 256 caracteres ou contém caracteres além de letras, dígitos, `-` e `_`. | Use um UUID ou um valor seguro semelhante. |
| `402` | `Insufficient credits` | Os créditos acabaram. Cada destinatário custa um crédito. | Compre créditos ou ative a [recarga automática](/pt/docs/billing/auto-refill/). |
| `403` | `Workspace not verified` | O workspace está no modo sandbox e um destinatário não é membro do workspace. | Solicite o [acesso de produção](/pt/docs/workspaces/production-access/). |
| `403` | `Domain paused` | O envio deste domínio está pausado por causa da [saúde de envio](/pt/docs/deliverability/sending-health/) dele. | Resolva o problema de bounces ou reclamações e fale com o suporte. |
| `403` | `Domain not authorized` | A chave de API é restrita a outro domínio de envio. | Envie do domínio da chave ou use outra chave. |
| `403` | `plan_required` | O recurso, como relatórios DMARC ou filtros de webhook, não está no seu plano. | Faça upgrade para o plano indicado em `required_plan`. |
| `403` | `mjml_alpha` | A requisição cria ou altera MJML, ou chama um endpoint de MJML. O MJML está em alfa e aberto apenas à equipe do Emailit. | Use outro editor ou outro tipo de conteúdo. Consulte [Editores e API de MJML](/pt/docs/templates/mjml/#who-can-use-mjml). |
| `404` | `Template not found` | O ID do template não existe, ou o alias não tem versão publicada. | [Publique](/pt/docs/api-reference/templates/publish/) uma versão do template. |
| `409` | `… already exists` | Você criou um objeto com um nome ou e-mail que já está em uso. | Use o objeto em `existing` ou escolha outro nome. |
| `409` | `Idempotency key in progress` | Outra requisição com a mesma chave ainda não terminou. | Aguarde um momento e tente de novo com a mesma chave. |
| `413` | `Message too large` | O e-mail, incluindo os anexos, tem mais de 40 MB. | Envie arquivos grandes como links em vez de anexos. |
| `422` | `Domain not verified` | O endereço `from` não está em um domínio de envio verificado deste workspace. | [Verifique o domínio](/pt/docs/domains/verification/) ou altere `from`. |
| `422` | `Attachment error` | A `url` de um anexo não pôde ser baixada em até 30 segundos, não está acessível ou tem mais de 25 MB. | Confira se a URL é pública e se o arquivo é pequeno o suficiente, ou envie `content` no lugar. |
| `422` | `Cannot cancel email`, `Cannot retry email`, `Cannot update email` | O status do e-mail não permite a ação, faltam menos de 3 minutos para o horário agendado, ou o conteúdo dele foi apagado. | Verifique o `status` do e-mail. Consulte as regras de cada endpoint. |
| `422` | `Page is too deep` | Você paginou além do offset 2.500 de [Listar eventos](/pt/docs/api-reference/events/list/). | Restrinja os resultados com filtros `type` ou `created_at`. |
| `429` | `Rate limit exceeded`, `Daily limit exceeded` | O workspace atingiu o limite de envio. | Aguarde `retry_after` segundos. Consulte [Limites de requisições](/pt/docs/api-reference/rate-limits/). |

## 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](/pt/docs/api-reference/rate-limits/#retry-with-backoff) 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`](/pt/docs/api-reference/idempotency/) para que o e-mail não seja enviado duas vezes.

## Veja também

  - [Autenticação](/pt/docs/api-reference/authentication/): Credenciais, escopos e todos os erros de autenticação.
  - [Limites de requisições](/pt/docs/api-reference/rate-limits/): Limites de envio, cabeçalhos e backoff.
  - [Idempotência](/pt/docs/api-reference/idempotency/): Tente enviar de novo sem enviar duas vezes.
  - [Logs de requisições](/pt/docs/logs/request-logs/): Veja a requisição e a resposta de cada chamada à API com falha.

---
Fonte: https://emailit.com/pt/docs/api-reference/errors/