---
title: "Erros da API"
description: "Códigos HTTP, objeto de erro e códigos de erro estáveis da API do Emissor de Nota, com a orientação de quando repetir uma chamada com segurança."
url: https://docs.emissordenota.com/erros
language: pt-BR
---
# Erros

A API usa os códigos HTTP convencionais e devolve sempre o mesmo objeto de erro: um código estável para o seu sistema tratar e uma mensagem para quem está depurando.

## Códigos HTTP

| Status | Significado | O que fazer |
| --- | --- | --- |
| 400 | Requisição malformada | Corrija o JSON ou os cabeçalhos |
| 401 | Não autenticado | Confira a chave e o ambiente |
| 403 | Sem permissão | Revise escopos, empresas e IPs liberados para a chave |
| 404 | Não encontrado | Confira o id e se o recurso é do mesmo ambiente da chave |
| 409 | Conflito | A operação já foi feita ou o estado da nota não permite a ação |
| 422 | Dados inválidos | Corrija os campos apontados em detalhes |
| 429 | Limite excedido | Espere o tempo indicado em Retry-After |
| 5xx | Falha do nosso lado | Repita com a mesma Idempotency-Key |

## Objeto de erro

**422 Unprocessable Entity**

```json
{
  "erro": {
    "codigo": "dados_invalidos",
    "mensagem": "Há campos inválidos na requisição.",
    "detalhes": [
      { "campo": "tomador.documento", "mensagem": "CNPJ com dígito verificador incorreto." },
      { "campo": "servico.valor", "mensagem": "Deve ser maior que zero." }
    ],
    "requisicao_id": "req_7Hc2Lq9Vx1"
  }
}
```

- `codigo` (string): Identificador estável do erro. Use este campo, e não a mensagem, na lógica do seu sistema.
- `mensagem` (string): Explicação em português. Pode mudar sem aviso.
- `detalhes` (array, só em 422): Presente em erros 422. Lista o campo e o problema de cada dado recusado.
- `requisicao_id` (string): Identificador da chamada. Informe ao suporte para localizarmos o registro.

## Códigos de erro comuns

O campo codigo é estável e pode ser usado na lógica do seu sistema. Estes aparecem em qualquer endpoint. Os específicos de cada recurso estão na referência.

| Status | Código | Quando acontece |
| --- | --- | --- |
| 401 | chave_invalida | A chave não existe, foi revogada ou é de outro ambiente. |
| 403 | empresa_nao_autorizada | A chave não tem acesso à empresa informada. |
| 403 | ip_nao_autorizado | A chamada veio de um IP fora da lista liberada para a chave. |
| 409 | idempotencia_em_conflito | A mesma Idempotency-Key chegou com outro corpo. |
| 422 | dados_invalidos | Há campos inválidos. O campo detalhes aponta cada um. |
| 429 | limite_excedido | A chave passou do limite de requisições por minuto. |

## Repetindo com segurança

Em falha de rede, 429 ou 5xx, repita com espera crescente: 1 s, 2 s, 4 s e assim por diante. Nas operações de escrita, mande sempre a mesma Idempotency-Key. Se a primeira tentativa já tiver sido processada, a API devolve o resultado original em vez de emitir outra nota.

| Resposta | Repetir? |
| --- | --- |
| 400 401 403 404 422 | Não. Corrija a requisição antes |
| 409 | Não. Consulte o estado atual do recurso |
| 429 | Sim, depois do tempo em Retry-After |
| 5xx ou sem resposta | Sim, com a mesma Idempotency-Key |

> **Falando com o suporte**
>
> Mande o requisicao_id da resposta. Com ele localizamos a chamada nos nossos registros.
