Códigos de erro

A API usa códigos HTTP padronizados e inclui detalhes no corpo:

Formato padrão

{
  "error":   "Mensagem humana do erro",
  "code":    "NFE_VALIDATION_001",
  "details": {
    "campo": "dest.cnpj",
    "motivo": "CNPJ inválido"
  }
}

Códigos HTTP

Código	Quando
200	OK
201	Criado (nota emitida, empresa cadastrada)
202	Aceito (enfileirado, aguardando processamento)
400	Requisição inválida (JSON malformado, validação)
401	Não autenticado (token ausente ou expirado)
403	Sem permissão (tentando acessar empresa alheia)
404	Recurso não encontrado
422	Validação falhou (ex: dados não atendem SEFAZ)
429	Rate limit excedido
500	Erro interno
503	SEFAZ indisponível (acionando contingência)

Códigos SEFAZ comuns

cStat	Descrição
100	Autorizado uso da NF-e
101	Cancelamento homologado
103	Lote recebido com sucesso
110	Uso Denegado
135	Evento registrado e vinculado a NF-e
204	Rejeição: duplicidade de NF-e
216	Rejeição: chave de acesso inválida
225	Rejeição: falha no schema XML
539	Rejeição: duplicidade de EPEC

Códigos SEFIN Nacional (NFS-e)

Prefixo do código indica origem:

• E* — Ambiente de Dados Nacional (ADN)
• X* — Comitê Gestor NFS-e

Exemplos:

• E001 — DPS com estrutura inválida
• E100 — Prestador não cadastrado
• X050 — CNPJ do emitente não autorizado

Erros customizados da API

Code	HTTP	Motivo
AUTH_001	401	Token ausente
AUTH_002	401	Token expirado
AUTH_003	403	Permissão negada
EMP_001	404	Empresa não encontrada
EMP_002	400	CNPJ já cadastrado
CERT_001	400	Certificado inválido
CERT_002	400	Senha do certificado incorreta
CERT_003	400	Certificado expirado
NFE_001	422	Falha na validação antes do envio
NFE_002	422	SEFAZ rejeitou (ver campo sefaz_cstat)
PLAN_001	402	Limite de notas do plano excedido
PLAN_002	402	Plano inativo