Erros da API
Toda resposta de emissão/cancelamento (mesmo com HTTP 200) traz um objeto
retorno_amigavel com um código estável, pensado pra você tratar por
switch/if no seu ERP sem parsear texto livre.
Formato
{
"status": "REJECTED",
"mensagem": "Rejeicao: Duplicidade de NF-e",
"retorno_amigavel": {
"codigo": "NFE_REJEITADA",
"mensagem": "Rejeicao: Duplicidade de NF-e",
"acao_recomendada": "Revise os dados e tente novamente."
},
"detalhes": { "cstat": "539", "xmotivo": "Rejeicao: Duplicidade de NF-e" }
}
codigo vem em duas formas: um código fixo por classe de falha (ex.:
NFE_CERTIFICADO_A1_AUSENTE), ou um código dinâmico
{PRODUTO}_{status} que espelha o campo status do documento (ex.:
NFE_AUTORIZADA, NFE_REJEITADA, NFSE_PROCESSING).
Trate pelo prefixo (NFE_/CTE_/CTEOS_/
MDFE_/NFSE_) + sufixo, não como uma lista fechada -- novos
sufixos de status seguem o mesmo padrão.
Códigos fixos conhecidos
| Código | Situação |
|---|---|
NFE_CERTIFICADO_A1_AUSENTE | Emitente sem certificado A1 ativo no momento da emissão/cancelamento de NF-e. |
NFE_EMISSAO_FALHOU | Falha no motor ao emitir NF-e (não é rejeição SEFAZ -- é erro interno de processamento). |
NFE_CANCELAMENTO_FALHOU | Falha no motor ao processar cancelamento de NF-e. |
CTE_CERTIFICADO_A1_AUSENTE | Emitente sem certificado A1 ativo (CT-e modelo 57). |
CTE_EMISSAO_FALHOU | Falha no motor ao emitir CT-e. |
CTE_CANCELAMENTO_FALHOU | Falha no motor ao cancelar CT-e. |
CTEOS_CERTIFICADO_A1_AUSENTE | Mesma condição, para CT-e OS (modelo 67). |
CTEOS_EMISSAO_FALHOU | Falha no motor ao emitir CT-e OS. |
MDFE_CERTIFICADO_A1_AUSENTE | Emitente sem certificado A1 ativo (emissão, cancelamento ou encerramento de MDF-e). |
MDFE_EMISSAO_FALHOU | Falha no motor ao emitir MDF-e. |
MDFE_CANCELAMENTO_FALHOU | Falha no motor ao cancelar MDF-e. |
MDFE_ENCERRAMENTO_FALHOU | Falha no motor ao encerrar MDF-e. |
NFSE_MUNICIPIO_SEM_PROVEDOR | Município do prestador ainda não tem provedor de NFS-e mapeado nesta API. |
NFSE_EMISSAO_FALHOU | Falha no motor ou no provedor municipal ao emitir NFS-e. |
NFSE_CANCELAMENTO_FALHOU | Falha no motor ou no provedor municipal ao cancelar NFS-e. |
Estados possíveis (campo status)
RECEIVED → PROCESSING → AUTHORIZED /
REJECTED / CANCELLED / ERROR. Como a emissão é
síncrona, na prática você recebe direto um dos estados terminais
(AUTHORIZED/REJECTED/ERROR) já na resposta do
POST -- RECEIVED/PROCESSING só aparecem se você
consultar via GET enquanto um lote está em fila na SEFAZ (raro, mas possível
em horários de instabilidade).
retorno_amigavel -- não há um serviço de listagem de erros
(GET /v1/erros) nem um enum publicado à parte. Esta página É o
catálogo; vamos mantê-la atualizada conforme novos códigos forem adicionados.