> ## Documentation Index
> Fetch the complete documentation index at: https://docs.invo.work/llms.txt
> Use this file to discover all available pages before exploring further.

# Erros

> Códigos de status e o envelope de erro padrão da API.

Erros usam um envelope JSON consistente:

```json theme={null}
{ "error": "mensagem legível" }
```

## Códigos de status

| Código                     | Significado                                               |
| -------------------------- | --------------------------------------------------------- |
| `200 OK`                   | Sucesso (consulta, download, inutilização).               |
| `201 Created`              | Nota criada e enfileirada para autorização.               |
| `202 Accepted`             | Cancelamento iniciado (processamento assíncrono).         |
| `401 Unauthorized`         | Credenciais HTTP Basic inválidas ou ausentes.             |
| `404 Not Found`            | Empresa (`X-Empresa-CNPJ`) ou nota não encontrada.        |
| `406 Not Acceptable`       | `Accept` não-JSON em endpoint JSON.                       |
| `409 Conflict`             | DANFE ainda não disponível (sem XML autorizado).          |
| `422 Unprocessable Entity` | Validação, empresa inapta ou rejeição da SEFAZ.           |
| `502 Bad Gateway`          | Falha de comunicação com a SEFAZ (veredito desconhecido). |

## Mensagens comuns (`422`)

| Mensagem                                                   | Contexto                                                            |
| ---------------------------------------------------------- | ------------------------------------------------------------------- |
| `Empresa não está apta a emitir NF-e`                      | Emissão/inutilização para empresa sem IE, CRT ou certificado ativo. |
| `Código externo já está em uso`                            | `codigo_externo` duplicado na empresa.                              |
| `Esta nota de produto já está cancelada`                   | Cancelamento de nota já cancelada.                                  |
| `Apenas notas de produto autorizadas podem ser canceladas` | Cancelamento de nota não autorizada.                                |
| `numero_final deve ser maior ou igual a numero_inicial`    | Faixa de inutilização inválida.                                     |

<Note>
  Por segurança, falhas de transporte com a SEFAZ retornam `502` com uma mensagem genérica (`Falha de comunicação com a SEFAZ`) — detalhes da exceção nunca são expostos no corpo. Para diagnóstico, consulte a trilha de eventos da nota.
</Note>