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.