Erros

Erros usam um envelope JSON consistente:

{ "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.

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.

Começando

Integração

Códigos de status

Mensagens comuns (`422`)

​Códigos de status

​Mensagens comuns (422)

Códigos de status

Mensagens comuns (`422`)