> ## Documentation Index > Fetch the complete documentation index at: https://docs.engineapi.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Erros e respostas > O envelope RFC 7807 de toda resposta de erro, os códigos HTTP e o catálogo completo de códigos de negócio da API. Toda resposta de erro da engineAPI segue o padrão **RFC 7807 (Problem Details)**, aplicado globalmente pelo filtro global de exceções. Não existe o formato antigo `{statusCode, error, message, sefazCode, sefazMessage}`: esses campos **não existem** no contrato real. *** ## Formato de Erro (RFC 7807) ```json theme={null} { "error": { "type": "https://engineapi.com.br/errors/BAD_REQUEST", "title": "Requisição Inválida", "status": 400, "detail": "SEFAZ rejeitou (CStat=539): Rejeicao: Duplicidade de NF-e", "erros": [ { "codigo": "539", "descricao": "Rejeicao: Duplicidade de NF-e" } ], "instance": "/v1/nfe", "requestId": "req_uofirusmuamw", "timestamp": "2026-07-05T11:06:14.453Z" } } ``` | Campo | Sempre presente? | Descrição | | ------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `error.type` | Sim | URI do tipo de erro (`https://engineapi.com.br/errors/`) | | `error.title` | Sim | Título legível do status HTTP | | `error.status` | Sim | Código HTTP (espelha o status da resposta) | | `error.detail` | Sim | Mensagem legível | | `error.errors[]` | Só em erro de **validação** (400 de payload malformado) | `{ field, message }` por campo inválido; `message` sempre em **português** (ex.: `"Tipo inválido: esperado texto, recebido nulo"`, `"Campo obrigatório"`), inclusive nos defaults de tipo/obrigatoriedade | | `error.erros[]` | Só em **rejeição fiscal** (SEFAZ/SEFIN) | `{ codigo, descricao }`, passthrough **verbatim**, sem tradução | | `error.details.camposDesconhecidos[]` | Só quando o payload traz campo que o contrato não conhece | `{ campo, caminho, objeto, motivo? }` por campo recusado. Ver [Campo desconhecido no payload](#campo-desconhecido-no-payload-400) | | `error.instance` | Sim | Path da requisição (já com `/v1`) | | `error.requestId` | Sim | Mesmo valor do header `X-Request-Id` | | `error.timestamp` | Sim | ISO 8601 | Não existem `sefazCode`/`sefazMessage` no envelope. O código e a mensagem da SEFAZ vêm em `error.erros[].codigo` e `error.erros[].descricao`. ## Timeout depois de emitir: consulte, não reemita Um timeout não prova que a SEFAZ recusou ou deixou de receber o documento. A autorização pode ter acontecido e apenas a resposta ter sido perdida. Por isso: * consulte o mesmo recurso com `GET /v1/nfe/{id}` ou `GET /v1/nfce/{id}`; * espere o webhook de autorização/rejeição; * não crie outra emissão com o mesmo pedido só porque o `POST` terminou em timeout. A engineAPI usa a chave persistida antes do envio para reconciliar o estado. Só retransmite automaticamente quando a consulta retorna que o documento não foi encontrado; qualquer estado fiscal real encerra a tentativa.

Como o slug de `error.type` nasce

O último segmento de `error.type` (o `` em `.../errors/`) é resolvido nesta ordem, pelo filtro global de exceções: 1. Se a exceção carrega um `code` (ou `error`) explícito e catalogado, entre eles os códigos de negócio (`CERTIFICADO_AUSENTE`, `CNPJ_CONFLICT` etc.), o slug é esse valor, normalizado (maiúsculas, espaços viram `_`). 2. Sem `code`/`error` explícito, o slug cai num mapa fixo por status HTTP (`400` vira `BAD_REQUEST`, `422` vira `UNPROCESSABLE_ENTITY`, `429` vira `RATE_LIMIT_EXCEEDED` etc.). 3. Payload de validação em formato de **array** (rejeição da validação de schema, global a toda a API) sempre vira `VALIDATION_ERROR`, independente do status. O filtro confere o slug no momento de enviar a resposta. Todo slug emitido pertence ao catálogo público de códigos de negócio ou à lista de códigos genéricos desta página. Se a exceção trouxer um código ausente do catálogo, a resposta conserva o status HTTP e usa `RECUSA_NAO_CATALOGADA`; a ocorrência é registrada para correção interna. O integrador pode tratar esse slug genérico sem depender do código inválido.

`errors[]` (validação) vs `erros[]` (fiscal): nunca os dois juntos

Os dois arrays de erro do envelope têm formato e origem **diferentes** e uma resposta carrega **no máximo um** dos dois: | | `error.errors[]` | `error.erros[]` | | -------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------- | | Quando aparece | Erro de **validação** do payload (campo ausente/tipo errado) | **Rejeição fiscal** (SEFAZ/SEFIN) | | Shape | `{ field, message }` | `{ codigo, descricao }` | | Idioma | `message` sempre em **português**, traduzido pela engineAPI | `descricao` **verbatim** da SEFAZ/SEFIN, sem tradução | | Slug de `error.type` | Sempre `VALIDATION_ERROR` | Varia (`BAD_REQUEST` na rejeição de emissão; outro slug em endpoints específicos) | ### `null`, `""` e campo ausente no `PATCH` O `GET` devolve `null` em todo campo que ainda não foi preenchido. Como a integração costuma ler o recurso, mudar um campo e devolver o objeto inteiro, o `PATCH` de emissor (`PATCH /v1/companies/{id}`) trata os três casos assim: | No corpo | Efeito | | ------------------- | ---------------------------------------------------------- | | Chave ausente | Mantém o valor atual | | `null` | Mantém o valor atual (o roundtrip do `GET` não apaga nada) | | `""` (string vazia) | **Limpa** o campo | ```javascript theme={null} // roundtrip do GET: os campos não preenchidos voltam null e são ignorados const { data } = await api.get(`/v1/companies/${id}`); await api.patch(`/v1/companies/${id}`, { ...data, ie: "123456789" }); // 200 // equivalente e mais enxuto: mande só o que mudou await api.patch(`/v1/companies/${id}`, { ie: "123456789" }); ``` `null` só desliga a escrita daquele campo. **Não afrouxa validação**: valor não-nulo continua passando por DV do CNPJ, formato e limite de tamanho, e erro de conteúdo segue `400` com `error.errors[]`. `sandbox` e `ambienteFiscal` iguais ao atual (roundtrip do GET) são ignorados; valor **diferente** recusa com `422 AMBIENTE_IMUTAVEL`, não é `200` silencioso.

Casas decimais em valores monetários (400)

Campos monetários de **total** da NF-e e da NFC-e cujo leiaute declara 2 casas decimais, como `valorFrete`, `valorSeguro`, `desconto`, `outrasDespesas`, valores de ICMS, ST, DIFAL e benefícios, `pagamentos[].valor`, `troco` e cobrança, aceitam no máximo 2 casas. Na NFS-e, a mesma regra vale para `servico.valorServicos`, descontos, deduções e retenções. Enviar uma fração de centavo devolve `400` antes de qualquer efeito. A engineAPI não arredonda frações de centavo intencionais nem transmite um centavo diferente do valor declarado. Só desconsidera o resíduo inevitável da representação binária de operações JavaScript, com tolerância proporcional à grandeza e muito menor que meio centavo. ```json theme={null} { "error": { "type": "https://engineapi.com.br/errors/VALIDATION_ERROR", "title": "Requisição Inválida", "status": 400, "detail": "Os dados enviados são inválidos", "errors": [ { "field": "items.0.valorFrete", "message": "Campo monetário de total aceita no máximo 2 casas decimais. Recebido: 1.005" } ] } } ``` | Entrada | Resultado | | ---------------------------------------------------------- | ---------------------------------------------------------- | | `1`, `1.5`, `1.55` | Aceita | | Resultado de `0.1 * 3` ou `1000000000 + 0.3` em JavaScript | Aceita como ruído de representação proporcional à grandeza | | `1.005`, `19.999`, `999999999.995` | `400` com campo, valor recebido e limite de 2 casas | `valorUnitario` é diferente: o tipo do leiaute permite até 10 casas decimais e essa precisão continua aceita. A mesma régua agora confere a parte inteira de todo formato decimal fixo. Um campo `13v2` aceita até 13 dígitos inteiros e 2 casas decimais; acima disso, a requisição devolve `400` antes de emitir. O teto exato `9999999999999.99` e a borda `99999999999.99` continuam válidos. A tolerância de ruído binário vale somente para a comparação das casas decimais e nunca aumenta esse teto. Campos numéricos fixos que não são dinheiro também seguem o dicionário. Na NF-e, `transporte.volumes[].pesoLiquido` e `pesoBruto` são `12v3`: aceitam no máximo 3 casas decimais. Por exemplo, `1.234` é aceito e `1.2345` devolve `400` com o caminho do volume e a mensagem `Campo de precisão fixa aceita no máximo 3 casas decimais. Recebido: 1.2345`. Na NFS-e, os valores `TSDec15V2` aceitam até 15 dígitos inteiros e 2 casas decimais. A largura também é derivada do dicionário da DPS, sem uma lista manual paralela. Formatos de precisão variável, como o `11v0-10` de `valorUnitario`, conservam sua faixa de casas; só o teto de 11 dígitos inteiros passa a ser aplicado. ***

Campo desconhecido no payload (400)

O contrato de emissão é **estrito**: campo que a engineAPI não conhece devolve `400` e **nada é emitido** (nenhum número fiscal é consumido, nenhuma fatura é criada). Vale para `POST /v1/nfe`, `POST /v1/nfe/batch`, `POST /v1/nfce` e `POST /v1/nfse`. A recusa acontece antes de qualquer processamento, inclusive quando você usa `resolverTributacao: true`. ```json theme={null} { "error": { "type": "https://engineapi.com.br/errors/VALIDATION_ERROR", "title": "Requisição Inválida", "status": 400, "detail": "Os dados enviados são inválidos: há campo não reconhecido no corpo da requisição", "errors": [ { "field": "items.0", "message": "items[0]: campo não reconhecido: \"NFref\". Sobre \"NFref\": O documento fiscal referenciado é suportado, mas com outro nome: o grupo é `referenciadas`, um array na raiz do corpo, com o campo `chaveAcesso` (a chave de acesso de 44 dígitos da nota original). `NFref` e `refNFe` são nomes do XML do leiaute. É esse grupo que as finalidades 2 (complementar), 3 (ajuste) e 4 (devolução) exigem. Campos aceitos em items[0]: codigo, ean, descricao, ncm, cest, cfop, unidade, quantidade, valorUnitario, valorTotal, desconto, icms, pis, cofins, ipi, ibsCbs. A engineAPI recusa campo desconhecido em vez de descartar em silêncio: campo fiscal ignorado sem aviso vira documento errado." } ], "details": { "camposDesconhecidos": [ { "campo": "NFref", "caminho": "items[0].NFref", "objeto": "items[0]", "motivo": "O documento fiscal referenciado é suportado, mas com outro nome: o grupo é `referenciadas`, um array na raiz do corpo, com o campo `chaveAcesso` (a chave de acesso de 44 dígitos da nota original). `NFref` e `refNFe` são nomes do XML do leiaute. É esse grupo que as finalidades 2 (complementar), 3 (ajuste) e 4 (devolução) exigem." } ] }, "instance": "/v1/nfe", "requestId": "req_uofirusmuamw", "timestamp": "2026-08-04T12:00:00.000Z" } } ``` | Campo de `camposDesconhecidos[]` | Descrição | | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `campo` | Nome da chave recusada, exatamente como você enviou | | `caminho` | Caminho completo até a chave (ex.: `items[0].icms.pRedBC`) | | `objeto` | Objeto que recusou (ex.: `items[0].icms`). Vazio quando a chave está na raiz do corpo | | `motivo` | Presente quando o campo existe no leiaute fiscal: ou o grupo ainda não é suportado, ou ele existe no contrato com outro nome | Use `caminho` para localizar o campo no seu payload e `motivo` para decidir o que fazer: sem `motivo`, é nome errado ou campo que não existe (a mensagem sugere o campo aceito mais parecido, quando há um, e avisa quando a diferença é só a caixa das letras). Com `motivo`, leia a frase: ela diz se o grupo não existe ainda ou para onde ir. ### Campos do leiaute que existem no contrato com outro nome O corpo da requisição não é o XML. Alguns grupos existem, com nome de campo próprio: | Você mandou (nome do XML) | Use no corpo | | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `comb`, `cProdANP`, `descANP`, `pGLP`, `pGNn`, `pGNi`, `vPart`, `UFCons` | `items[].combustivel`, com os mesmos campos dentro dele. Ver o guia de Combustíveis e GLP e a [referência de campos](/api-reference/campos-nfe) | | `NFref`, `refNFe` | `referenciadas`, um array na raiz do corpo, com o campo `chaveAcesso` (a chave de acesso de 44 dígitos da nota original). Ver [Documento referenciado inválido](#documento-referenciado-invlido-e-a-forma-sem-pagamento-422) abaixo | ### Recursos fiscais suportados por passthrough Estes grupos entram no documento depois de validados. A API verifica forma e coerência, mas não apura os valores nem consulta a regra da UF: | Recurso | Campos no corpo | Situação | | ------------------ | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | DIFAL | `items[].icms.ufDestino` (`vBCUFDest`, `pICMSUFDest`, `vICMSUFDest`, `vICMSUFRemet` e, quando aplicável, FCP) | **Suportado por passthrough validado** para emissor `crt: 2` ou `crt: 3`. Informe a partilha calculada conforme a legislação da UF de destino; a API valida e transcreve, mas não calcula o DIFAL. Emissor `crt: 1` ou `crt: 4` recebe `422 DIFAL_NAO_APLICAVEL`. Veja [DIFAL](/guides/difal) | | Benefícios de ICMS | `pRedBC`, `vICMSDeson`, `motDesICMS`, `vICMSDif`, `pDif` | **Suportados nos grupos e CST aplicáveis.** O emitente informa os valores e o ato concessório; a API valida o formato e a coerência, sem consultar a tabela da UF. Veja [Benefícios fiscais de ICMS](/guides/beneficios-icms) | ### Campos do leiaute que a engineAPI ainda não suporta Estes são campos **reais** da NF-e. Enviar qualquer um deles devolve `400` com o motivo específico, em vez de a nota sair sem o grupo: | Grupo | Campos que disparam a recusa | Situação | | ------------------------------------------------ | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Documento referenciado, variantes fora do escopo | `refNF`, `refNFP`, `refCTe`, `refECF`, `refNFeSig` | Nota fiscal de papel modelo 1/1A ou 2, nota de produtor rural, CT-e, cupom fiscal de ECF e a chave com código numérico zerado ainda não são suportados. O documento referenciado por chave de acesso É suportado (NF-e `55`, NFC-e `65` e CF-e SAT `59`): use `referenciadas[].chaveAcesso` | | Transporte detalhado | `veiculo`, `veicTransp`, `placa`, `rntc`, `reboque`, `lacres`, `retTransp`, `balsa`, `vagao` | Em transporte, hoje o contrato aceita `modFrete`, `transportadora` e `volumes` | | Rastreabilidade | `rastro`, `nLote`, `qLote`, `dFab`, `dVal` | Ainda não suportado | | Medicamentos | `med`, `cProdANVISA`, `vPMC` | Ainda não suportado | | Informação por item | `infAdProd`, `gta` | Ainda não suportado. É onde entraria a Guia de Trânsito Animal | | Importação e exportação | `DI`, `adi`, `II`, `vDespAdu`, `vIOF`, `detExport`, `exporta` | Ainda não suportado | A lista acima muda quando um grupo passa a ser suportado. O campo sai da recusa e entra no contrato, e a [referência de campos](/api-reference/campos-nfe) passa a listá-lo. ### O que muda para quem já integra Se o seu payload usa apenas campos documentados, **nada muda**: mesma requisição, mesma resposta. Se você envia algum campo a mais, o que antes era ignorado em silêncio agora é `400`. Foi uma decisão deliberada, e o motivo é o desfecho que o silêncio produzia: | Você enviava | Antes | Agora | | ----------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | | `NFref` numa devolução | Campo descartado, nota transmitida, SEFAZ rejeitava com `cStat 321` **depois** de consumir o número | `400` antes de consumir número | | `veiculo` no transporte | Campo descartado, SEFAZ rejeitava com `cStat 544` | `400` com a lista do que o transporte aceita | | Grupo `comb` num GLP | Campo descartado e a nota saía **autorizada sem o grupo obrigatório**, fiscalmente irregular | `400` apontando o campo certo: `items[].combustivel` | | Campos de DIFAL | Campos descartados, seguido de `422` genérico | `400` nomeando cada campo | No **lote** (`POST /v1/nfe/batch`) a recusa é tudo ou nada: uma chave desconhecida em uma única nota recusa o envio inteiro com `400`, e **nenhuma** nota é enfileirada. Antes o lote respondia `201` e descartava a chave. O caminho é o mesmo do singular: `caminho` em `camposDesconhecidos` diz a nota pelo índice (ex.: `notas[2].items[0].comb`). Checklist de migração: 1. Rode seus payloads de homologação uma vez. Campo a mais aparece em `details.camposDesconhecidos` com o caminho exato. 2. Remova os campos sem `motivo` (nome errado ou campo inexistente). 3. Para os campos com `motivo`, o grupo ainda não é suportado: retire do payload e trate o cenário fora da API até o suporte existir. ### Quando a SEFAZ rejeita: como ver o que foi transmitido Recusa da SEFAZ vem com o código (`cStat`) e o motivo verbatim, mas quem depura precisa do documento que saiu daqui, não só da mensagem. O XML **transmitido** de uma emissão rejeitada fica guardado e é recuperável pelo `id` da nota: ``` GET /v1/nfe/xml/{id} ``` A mesma rota serve os dois casos: com a chave de acesso (44 dígitos) devolve o XML autorizado; com o `id`, devolve também o de uma rejeitada, que não tem chave. É o documento assinado exatamente como foi enviado, então dá para conferir tag a tag o que a SEFAZ recusou. ### `finNFe` 2, 3 ou 4 sem o documento referenciado (422) `ide.finNFe: 2` (complementar), `3` (ajuste) ou `4` (devolução) pressupõem, no leiaute, o documento fiscal referenciado apontando a nota original: sem ele o documento sai incompleto. A exigência é **regra de validação de negócio da SEFAZ** (tabela `cStat`), não uma restrição do XSD (o grupo é `minOccurs="0"` no schema): sem ele, a SEFAZ rejeitaria a nota **depois** de consumir o número, com `cStat 254` na finalidade 2 e `cStat 321` na finalidade 4 (a tabela não tem código dedicado para a 3). A engineAPI recusa as três antes, com `422`, apontando o campo do contrato que resolve: ```json theme={null} { "error": { "type": "https://engineapi.com.br/errors/FINALIDADE_SEM_NFREF", "title": "Entidade Não Processável", "status": 422, "detail": "\"finNFe\": 2 (complementar) exige o documento fiscal referenciado para a SEFAZ aceitar a operação: sem ele a nota sai rejeitada com cStat 254 (\"NF-e complementar não possui NF referenciada\"). Informe \"referenciadas\": [{ \"chaveAcesso\": \"<44 dígitos da nota original>\" }] no corpo da requisição, ou emita com \"finNFe\": 1 (normal). Cobertura atual: https://docs.engineapi.com.br/cobertura. Nada foi emitido; nenhum número fiscal foi consumido.", "instance": "/v1/nfe", "requestId": "req_abc123", "timestamp": "2026-08-07T18:13:00.000Z" } } ``` ```json theme={null} { "error": { "type": "https://engineapi.com.br/errors/FINALIDADE_SEM_NFREF", "title": "Entidade Não Processável", "status": 422, "detail": "\"finNFe\": 4 (devolução/retorno) exige o documento fiscal referenciado para a SEFAZ aceitar a operação: sem ele a nota sai rejeitada com cStat 321 (\"NF-e de devolução de mercadoria não possui documento fiscal referenciado\"). Informe \"referenciadas\": [{ \"chaveAcesso\": \"<44 dígitos da nota original>\" }] no corpo da requisição, ou emita com \"finNFe\": 1 (normal). Cobertura atual: https://docs.engineapi.com.br/cobertura. Nada foi emitido; nenhum número fiscal foi consumido.", "instance": "/v1/nfe", "requestId": "req_abc124", "timestamp": "2026-08-07T18:13:00.000Z" } } ``` `finNFe: 3` (ajuste) recusa com o mesmo `code`, mas sem cravar `cStat`: a mensagem diz "sem ele a SEFAZ rejeitaria a nota depois de a numeração já ter sido consumida", porque a tabela `cStat` não tem entrada dedicada confirmada para essa finalidade. `finNFe` ausente ou `1` (normal) segue emitindo sem mudança. Ver [Cobertura fiscal](/cobertura).

Documento referenciado inválido e a forma Sem Pagamento (422)

`referenciadas[].chaveAcesso` vira a tag do documento referenciado numa nota assinada, e a forma de pagamento `"90"` (Sem Pagamento) descreve uma operação sem contraprestação (remessa, bonificação, comodato, devolução). Quatro recusas cercam os dois campos, todas `422` e todas antes de consumir número fiscal. **`REFERENCIADA_INVALIDA`**: a chave de `referenciadas[].chaveAcesso` não tem 44 dígitos numéricos, o código de UF embutido nela não existe na tabela do IBGE, o ano/mês embutido não traz um mês entre `01` e `12`, o modelo embutido não é NF-e (`55`), NFC-e (`65`) nem CF-e SAT (`59`), o número do documento embutido veio zerado, o dígito verificador não fecha pelo módulo 11, a mesma chave aparece duas vezes no array, o array tem mais de 500 entradas (o teto do grupo no leiaute), a chave aponta para a **própria nota** que está sendo emitida, ou `finNFe: 2` (complementar) veio com mais de uma referência (a complementar complementa uma nota específica): ```json theme={null} { "error": { "type": "https://engineapi.com.br/errors/REFERENCIADA_INVALIDA", "title": "Entidade Não Processável", "status": 422, "detail": "\"referenciadas[0].chaveAcesso\" não é uma chave de acesso válida: a chave de acesso tem exatamente 44 dígitos, sem espaços, pontos ou letras. Nada foi emitido; nenhum número fiscal foi consumido.", "instance": "/v1/nfe", "requestId": "req_abc125", "timestamp": "2026-08-07T18:13:00.000Z" } } ``` Chave repetida no mesmo array recusa com a mesma mensagem de campo, motivo diferente: ```json theme={null} { "error": { "type": "https://engineapi.com.br/errors/REFERENCIADA_INVALIDA", "title": "Entidade Não Processável", "status": 422, "detail": "\"referenciadas[1].chaveAcesso\" repete uma chave já informada em \"referenciadas\". Cada documento referenciado entra uma única vez. Nada foi emitido; nenhum número fiscal foi consumido.", "instance": "/v1/nfe", "requestId": "req_abc126", "timestamp": "2026-08-07T18:13:00.000Z" } } ``` **`SEM_PAGAMENTO_INVALIDO`**: a forma `"90"` usada numa combinação que o leiaute não comporta: `valor` diferente de zero na entrada com forma `"90"` (a SEFAZ rejeita com o código 904), ou a forma `"90"` presente junto de outra forma de pagamento no mesmo documento (a forma descreve o documento inteiro, não convive com mais nenhuma entrada em `pagamentos`): ```json theme={null} { "error": { "type": "https://engineapi.com.br/errors/SEM_PAGAMENTO_INVALIDO", "title": "Entidade Não Processável", "status": 422, "detail": "\"pagamentos[0]\" usa a forma \"90\" (sem pagamento) com \"valor\": 10.00. A SEFAZ rejeita a combinação com o código 904 (\"informado indevidamente campo valor de pagamento\"): sem pagamento significa valor zero. Envie \"valor\": 0 nessa entrada, ou troque a forma pela que representa o pagamento real. Nada foi emitido; nenhum número fiscal foi consumido.", "instance": "/v1/nfe", "requestId": "req_abc127", "timestamp": "2026-08-07T18:13:00.000Z" } } ``` **`SEM_PAGAMENTO_VEDADO_NFCE`**: a forma `"90"` numa NFC-e (modelo 65). É vedação da SEFAZ, não limitação da engineAPI: a NFC-e registra venda a consumidor final com contraprestação; operação sem pagamento se documenta em NF-e (modelo 55): ```json theme={null} { "error": { "type": "https://engineapi.com.br/errors/SEM_PAGAMENTO_VEDADO_NFCE", "title": "Entidade Não Processável", "status": 422, "detail": "\"pagamentos[0].forma\": \"90\" (sem pagamento) não é aceito na NFC-e: a SEFAZ rejeita o documento com o código 899 (\"informado incorretamente o campo meio de pagamento\"). A NFC-e registra venda a consumidor final com pagamento; operação sem contraprestação (remessa, bonificação, comodato, devolução) se documenta em NF-e (modelo 55), onde a forma \"90\" é aceita. Nada foi emitido; nenhum número fiscal foi consumido.", "instance": "/v1/nfce", "requestId": "req_abc128", "timestamp": "2026-08-07T18:13:00.000Z" } } ``` **`FINALIDADE_EXIGE_SEM_PAGAMENTO`**: o inverso, `finNFe: 3` (ajuste) ou `4` (devolução) com uma forma de pagamento diferente de `"90"`. As duas finalidades registram a operação, não uma cobrança, e a SEFAZ rejeita a combinação com o código 871: ```json theme={null} { "error": { "type": "https://engineapi.com.br/errors/FINALIDADE_EXIGE_SEM_PAGAMENTO", "title": "Entidade Não Processável", "status": 422, "detail": "\"finNFe\": 4 (devolução/retorno) exige forma de pagamento \"90\" (sem pagamento): o documento registra a operação, não uma cobrança, e a SEFAZ rejeita a nota com o código 871 quando o meio de pagamento é outro. Recebido: \"01\". Envie \"pagamentos\": [{ \"forma\": \"90\", \"valor\": 0 }]. Nada foi emitido; nenhum número fiscal foi consumido.", "instance": "/v1/nfe", "requestId": "req_abc129", "timestamp": "2026-08-07T18:13:00.000Z" } } ``` Uma devolução completa combina os três: `finNFe: 4`, `referenciadas` apontando a nota original, e `pagamentos` com uma única entrada, forma `"90"` e `valor: 0`. Ver [Cobertura fiscal](/cobertura) para o escopo exato de `referenciadas` (hoje só a chave de acesso de NF-e/NFC-e). *** ## Códigos HTTP | Código | Significado | Quando ocorre | | ----------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `200`/`201` | Sucesso | Requisição processada com sucesso | | `400` | Bad Request | JSON inválido, campo obrigatório ausente/nome errado, **ou rejeição da SEFAZ/SEFIN** (`error.erros[]`) | | `401` | Unauthorized | Token ausente, inválido ou expirado. Também responde 401 a chave de API de um parceiro desativado pela plataforma (as chaves são revogadas na desativação; fale com o suporte) | | `402` | Payment Required | Assinatura com pagamento pendente (`PAYMENT_REQUIRED`). Só bloqueia métodos que não são `GET` | | `403` | Forbidden | Sem permissão, assinatura cancelada/inexistente, ou `ek_test_` usada contra emissor de produção | | `404` | Not Found | Recurso (nota, empresa, webhook, CNPJ/CPF consultado) não encontrado. Inclusive para não revelar recursos de outro partner | | `409` | Conflict | CNPJ já cadastrado como emissor: `CNPJ_CONFLICT`, mesmo code/mensagem seja o CNPJ seu ou de outro parceiro (anti-enumeração, #383) | | `413` | Payload Too Large | Upload de certificado A1 acima de 5MB (`PAYLOAD_TOO_LARGE`) | | `422` | Unprocessable Entity | Sempre ANTES de qualquer chamada à SEFAZ/SEFIN/worker/provedor externo. Ver [Catálogo de códigos de negócio](#catalogo-de-codigos-de-recusa) para a lista completa de origens | | `429` | Too Many Requests | Rate limit do plano excedido (`RATE_LIMIT_EXCEEDED`), ou rate limit do provedor de consulta externa de CNPJ/CPF (`TOO_MANY_REQUESTS`) | | `500` | Internal Server Error | Erro interno. Contate o suporte | | `502` | Bad Gateway | Falha ao consultar provedor externo (CNPJ/CPF) sem categoria mais específica | | `503` | Service Unavailable | SEFAZ/SEFIN, ou o provedor externo de consulta de CPF, temporariamente indisponível | **Rejeição da SEFAZ/SEFIN é sempre `400`, nunca `422`.** Todo `422` desta API acontece ANTES de qualquer chamada à SEFAZ/SEFIN/worker de emissão/provedor externo: a validação é sempre local. Não trate rejeição fiscal e `422` como sinônimos. ***

Catálogo de códigos de negócio

Todo código abaixo é o `code` que vira o slug de `error.type` (ver [Como o slug nasce](#como-o-slug-de-errortype-nasce)). A tabela é **gerada da fonte** — `apps/api/src/common/errors/catalogo-recusas.ts`, o registro único de onde cada código é lançado — e cobre os `code`s de negócio ESTÁVEIS das famílias `400`/`402`/`403`/`409`/`422`, fora dos slugs genéricos por status (`BAD_REQUEST`, `UNAUTHORIZED`, `VALIDATION_ERROR` etc., já cobertos em [Códigos HTTP](#cdigos-http)) e fora da rejeição SEFAZ/SEFIN (`erros[]`, passthrough do Fisco — ver [Rejeição SEFAZ/SEFIN](#rejeio-sefazsefin-400-exemplos)). **Código que você não reconhece:** consulte a versão atual deste catálogo e mostre `error.detail` ao usuário. `RECUSA_NAO_CATALOGADA` indica que a API substituiu um código não registrado; informe `error.requestId` ao suporte. `MUNICIPIO_NAO_ADERENTE_PADRAO_NACIONAL` (422) é o mesmo código do aviso aditivo `avisos[]` no cadastro da empresa: município que não adere ao Padrão Nacional da NFS-e neste ambiente. Na emissão, recusa **antes de numerar** se o espelho já confirma `nao_aderente`; se a SEFIN ainda devolver `E0037`, a mensagem original segue em `details.mensagemSefin`. `desconhecido` nunca dispara este código. | Código (`error.type`) | HTTP | Quando ocorre | O que fazer | Documentos | | ---------------------------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | | `SEQUENCIA_DESSINCRONIZADA` | `400` | A SEFAZ devolveu CStat 539 (duplicidade com chave de acesso diferente): o número que o motor alocou (ou o `numero` explícito) já está autorizado na SEFAZ sob outra chave. O contador local estava atrás — restore, migração ou teste antigo. Se a numeração era automática, o motor consulta a chave própria, avança `fiscal_sequences` e reemite uma vez; este código só aparece quando a reemissão não fecha o gap ou o `numero` veio no payload. | Informe `numero` maior que `details.informeNumeroMaiorQue` (o último nNF que a SEFAZ já tem nesta série) ou omita `numero` e tente de novo — a próxima alocação automática já sai na frente do contador reconciliado. Não reenvie a mesma Idempotency-Key. | NF-e, NFC-e | | `PAYMENT_REQUIRED` | `402` | A assinatura do partner está com pagamento pendente — bloqueia chamadas autenticadas até a regularização. | Regularize o pagamento da assinatura para voltar a usar a API. | Comum | | `AMBIENTE_DE_TESTE_SEM_ESCRITA_WEBHOOK` | `403` | Chave de teste (`ek_test_`) chamando uma rota de ESCRITA do webhook — `PATCH /v1/webhooks/config`, `POST /v1/webhooks/secret/regenerate`, ou o retry/purge da Dead Letter Queue (#992). O `webhookSecret` é único por parceiro, não por ambiente. | Use sua `ek_live_` ou o login do dashboard para configurar/rotacionar o webhook. Leitura (`GET /config`, `GET /logs`, `GET /dlq`) continua aberta pra `ek_test_`. | Comum | | `PRAZO_CANCELAMENTO_EXPIRADO` | `403` | Pedido de cancelamento fora do prazo do modelo: 24h para NF-e (Ajuste SINIEF 07/05) ou 30min para NFC-e (Ajuste SINIEF 07/18), contados da autorização. | Cancelamento fora do prazo não é possível pela API — trate por carta de correção (quando aplicável) ou pelos canais fiscais competentes. | NF-e, NFC-e | | `CANCELAMENTO_INDISPONIVEL` | `409` | O evento de cancelamento foi transmitido mas a SEFAZ não devolveu nenhum evento (lista de retorno vazia) — acontece quando o cancelamento sai poucos segundos depois da autorização, antes de ela ser processada por completo. O motor já repete a transmissão internamente com teto antes de recusar; nada foi cancelado. | Repita o cancelamento após `details.retryAfter` segundos (5). Se persistir, consulte a nota antes de repetir — a recusa não altera o estado do documento na SEFAZ. | NF-e, NFC-e | | `CHAVE_PERSISTIDA_DIVERGENTE` | `409` | Uma gravação tenta substituir ou apagar a chave de acesso já persistida de uma NF-e/NFC-e sem confirmação de que a chave anterior está INEXISTENTE na SEFAZ. Vale para qualquer tipo de emissão (normal, contingência SVC ou offline) e para documento emitido antes da coluna tpEmis existir. | Consulte a situação da chave original. Se o desfecho estiver indeterminado, aguarde a reconciliação; não reemita o mesmo número com outra chave. | NF-e, NFC-e | | `CNPJ_CONFLICT` | `409` | `POST /v1/companies` (ou `PATCH`) com um CNPJ já cadastrado como emissor — seu ou de outro parceiro (`Issuer.cnpj` é único globalmente na base, não por partner). | Se o CNPJ é seu, veja `GET /v1/companies` para recuperar o cadastro existente. Se é de outro parceiro, use `POST /v1/companies/transfer-request`. Mensagem e `code` são IDÊNTICOS nos dois casos, de propósito (anti-enumeração, #383): a API nunca revela de quem é o CNPJ conflitante. | Comum | | `DANFE_INDISPONIVEL` | `409` | Documento sem chave de acesso (ainda não autorizado), ou sem XML autorizado armazenado neste ambiente (nota de sandbox, ou autorizada em outro ambiente) — o DANFE é gerado a partir do XML autorizado. | Consulte o status da nota e tente novamente após a autorização; para nota sandbox não há DANFE real. | NF-e, NFC-e | | `DANFSE_INDISPONIVEL` | `409` | JOT-265 — o DANFSe (PDF) da NFS-e não pode ser servido por condição PERMANENTE: o serviço oficial de DANFSe respondeu 404/410/501 para a chave (o 501 é o "serviço movido de endereço" do Padrão Nacional), ou o certificado A1 do emissor está instalado mas não pôde ser processado (senha/arquivo inválidos). A NFS-e continua autorizada; nada foi alterado no documento. | Não repita a chamada: ela devolve o mesmo erro. Use o XML autorizado em `GET /v1/nfse/xml/{id}` enquanto o serviço oficial de DANFSe não atender; se a causa for o certificado, reenvie o A1 do emissor. Indisponibilidade TEMPORÁRIA do serviço oficial não cai aqui — sai como `502`, aí sim com retry. | NFS-e | | `NUMERO_JA_UTILIZADO` | `409` | `numero` explícito do payload já foi usado por outro documento deste emissor (mesmo `issuerId`/modelo/série). | Use outro número, ou omita o campo `numero` para numeração automática do emissor. | NF-e, NFC-e | | `PARTNER_ALREADY_HAS_OWNER` | `409` | O parceiro já possui membro ou convite de proprietário pendente. | Não atribua outro dono; use a gestão de membros do próprio parceiro. | — | | `PARTNER_COM_DOCUMENTO_FISCAL` | `409` | Pedido de desativação (`DELETE /v1/admin/partners/:id`) de um parceiro cujos emissores já têm documento fiscal emitido (NF-e/NFC-e, NFS-e, MDF-e ou CT-e). Nada é escrito. | Dado fiscal não se apaga: suspenda a assinatura (`PATCH /v1/admin/partners/:id/status` com `SUSPENDED`) ou transfira os emissores antes de desativar o parceiro. | — | | `RETOMADA_CONTINGENCIA_NAO_RESTAURAVEL` | `409` | `POST /v1/nfe` ou `POST /v1/nfce` retomando uma `Invoice` de tentativa anterior (`CREATED`/`TRANSMITTING`/`ERROR`) cuja chave de acesso persistida usa `tpEmis` fora do conjunto restaurável (NF-e: `{1, 6, 7}`; NFC-e: `{1}`; a contingência offline tpEmis=9 fica fora desta retomada). | Não há reenvio automático seguro: contate o suporte antes de retransmitir manualmente esta Invoice. | NF-e, NFC-e | | `AMBIENTE_IMUTAVEL` | `422` | `PATCH /v1/companies/:id` com `sandbox` ou `ambienteFiscal` diferente do valor atual do emissor. O PATCH genérico não muda ambiente: valor diferente recusa; valor igual ao atual (roundtrip do GET) é ignorado sem erro. | Para `sandbox`, peça ao SUPERADMIN `PATCH /v1/admin/companies/:id/sandbox`. Para `ambienteFiscal` (1=produção, 2=homologação), use `PATCH /v1/companies/:id/ambiente`. Reenviar o valor atual (roundtrip do GET) não recusa. | Comum | | `BASE_FISCAL_NAO_CONFIAVEL` | `422` | JOT-103 — emissão com `resolverTributacao: true` (Cérebro Fiscal) em que a base de regras fiscais consultada por aquele caminho está VAZIA, NUNCA SINCRONIZADA com a fonte oficial ou não conferida contra ela há mais tempo que o teto (`details.tetoIdadeHoras`, 168 h por padrão). Recusa ANTES de reservar numeração: nenhum documento é emitido e nenhum número fiscal é consumido. Emissão com a tributação informada no payload NÃO depende dessa base e nunca cai aqui; emissor sandbox também não (emite, e o fato sai como aviso no log e em `GET /v1/fiscal/prontidao`). | Para emitir agora, envie a tributação no payload (`csosn`/`cst`/`ibsCbs`) sem `resolverTributacao`. `details.baseFiscal[]` traz, por tabela, o motivo (`VAZIA`/`NUNCA_SINCRONIZADA`/`DESATUALIZADA`), a última sincronização bem-sucedida e a idade em horas; `GET /v1/fiscal/prontidao` responde a mesma coisa antes de você montar o documento. | NF-e, NFC-e, NFS-e | | `CADASTRO_EMISSOR_INCOMPLETO` | `422` | O cadastro do emissor está incompleto para emitir NF-e/NFC-e: falta Inscrição Estadual válida (2 a 14 dígitos, ou "ISENTO" maiúsculo) ou algum campo de endereço (logradouro, bairro, município, UF, CEP, código IBGE). | Complete o cadastro do emissor (endereço e IE) antes de emitir. `details.camposFaltando[]` nomeia os campos; nenhum número fiscal é consumido. | NF-e, NFC-e | | `CADASTRO_NFSE_INCOMPLETO` | `422` | Cadastro do emissor incompleto para NFS-e: falta código IBGE do município, serviço padrão (item LC 116), código de tributação nacional padrão, ou — para ME/EPP no Simples — o percentual total de tributos (pTotTribSN) padrão. Inscrição Municipal (IM) é opcional no leiaute do Padrão Nacional. | Complete o cadastro do emissor em Empresas antes de emitir NFS-e. `details.camposFaltando[]` nomeia os campos. | NFS-e | | `CERTIFICADO_AUSENTE` | `422` | O emissor não é sandbox e não tem certificado A1 instalado (`certFilename`/`certPassword`), num caminho que exige o provider real: emissão de NF-e/NFC-e/NFS-e, consulta de Distribuição DFe, ou promoção a SEFAZ real (`PATCH /v1/admin/companies/:id/sandbox` com `sandbox: false`). | Instale o certificado A1 do emissor em Certificados antes de emitir, consultar ou promover. Emissor sandbox nunca precisa. Em `prontoPara.nfse`, o campo em `faltando` é `certificado` — distinto de vencido ou de outro CNPJ. | NF-e, NFC-e, NFS-e | | `CERTIFICADO_OUTRO_CNPJ` | `422` | O CNPJ extraído do certificado A1 (`certCnpj`, OID ICP-Brasil 2.16.76.1.3.3) tem raiz (8 dígitos) diferente da do emissor cadastrado. Filial com e-CNPJ da matriz (mesma pessoa jurídica) não recusa. Só dispara quando o metadado existe — upload legado sem `certCnpj` não inventa divergência. | Envie o certificado A1 da mesma pessoa jurídica do emissor (CNPJ raiz). `details.camposFaltando` traz `certificadoOutroCnpj`. O CNPJ do certificado não é ecoado na resposta. | NFS-e | | `CERTIFICADO_SENHA_INVALIDA` | `422` | O emissor tem certificado A1 (`certPassword`) ou CSC configurado, mas a decifra em repouso falha: chave de cifra rotacionada sem a antiga (`ENCRYPTION_KEY_OLD`), blob corrompido, ou formato v1/v2 legado recusado (`CryptoUtil.decrypt` é fail-loud desde o #665). Distinto de `CERTIFICADO_AUSENTE` — aqui o segredo EXISTE, só não decifra. | Reenvie o certificado A1 (ou o CSC) do emissor em Certificados/Empresas. Se o erro persistir logo após uma rotação de chave de cifra, contate o suporte — pode faltar a chave antiga para re-cifrar o backlog. | NF-e, NFC-e, NFS-e | | `CERTIFICADO_VENCIDO` | `422` | O emissor tem certificado A1 instalado, mas `certExpiry` já passou. A NFS-e recusa no `prontoPara.nfse` e no pré-voo da emissão (antes de alocar nDPS). | Renove o A1 e reenvie em Certificados. `details.camposFaltando` traz `certificadoVencido` (não o genérico `certificado`) e `details.certExpiry` a data persistida. Emissor sandbox nunca cai nesta recusa. | NFS-e | | `CEST_INVALIDO` | `422` | `cest` do item fora do formato/domínio esperado pelo leiaute. | Informe um CEST válido (7 dígitos, tabela CEST vigente) ou omita o campo quando não aplicável. | NF-e, NFC-e | | `CFOP_IDDEST_DIVERGENTE` | `422` | Itens da mesma nota com CFOPs cujo 1º dígito mapeia `idDest` diferentes (interna/interestadual/exterior) — o documento tem um único `idDest`. | Use CFOPs cujo 1º dígito seja consistente com o `idDest` da operação em todos os itens. | NF-e, NFC-e | | `CHAVE_INVALIDA` | `422` | Consulta de Distribuição DFe por chave de acesso (`GET .../dfe/:issuerId/chave/:chave`) com chave fora de 44 dígitos. | Informe a chave de acesso com exatamente 44 dígitos. | Comum | | `CNAE_NAO_CADASTRADO` | `422` | Chamada consultiva do Cérebro Fiscal (ex.: resolução de NCM por descrição) para um emissor sem `cnae` cadastrado, e sem `{ cnae }` informado diretamente na chamada. | Cadastre o CNAE da empresa (Companies/dashboard), ou informe `{ cnae }` diretamente na chamada. | Comum | | `COBRANCA_INVALIDA` | `422` | Grupo `cobr` (fatura + duplicatas) com soma das duplicatas divergente do líquido da fatura, `valorLiquido != valorOriginal - valorDesconto`, `valorDesconto > valorOriginal`, vencimento inválido/fora de ordem, ou `duplicatas` enviada sem `fatura`. | Corrija os valores/datas do grupo `cobr` até fecharem entre si; envie `fatura` junto de `duplicatas` ou remova `duplicatas`. | NF-e | | `COBRANCA_NAO_SUPORTADA_NFCE` | `422` | Grupo `cobr` (fatura a prazo) informado numa NFC-e (modelo 65) — regra de negócio: NFC-e é venda com pagamento imediato ao consumidor final. | Não envie o grupo `cobr` em emissão de NFC-e. | NFC-e | | `COFINS_NAO_SUPORTADO` | `422` | `cofins` do item fora do domínio de CST que o motor escreve hoje. | Consulte `docs.engineapi.com.br/cobertura` para o CST de COFINS suportado, ou omita o grupo. | NF-e, NFC-e | | `COMBUSTIVEL_GRUPO_OBRIGATORIO` | `422` | CFOP de operação com combustível sem o grupo `comb` no item (MOC 7.0 Anexo I, RV LA01-20 — rejeição SEFAZ 660). | Informe o grupo `comb` (dados de combustível) no item quando o CFOP for de operação com combustível. | NF-e, NFC-e | | `COMBUSTIVEL_INVALIDO` | `422` | Grupo `comb` informado de forma que o documento não representa: percentuais de GLP fora do domínio, somatório de percentuais ≠ 100, GLP sem `vPart`, GLP com unidade ≠ kg, ou UF de consumo inexistente. | Corrija o grupo `comb` conforme a mensagem de erro específica (fonte: MOC 7.0 Anexo I). | NF-e, NFC-e | | `CONTINGENCIA_SEM_INDISPONIBILIDADE` | `422` | `contingencia: true` numa UF que o monitoramento da engineAPI vê DISPONÍVEL, com a instalação configurada com `SEFAZ_CONTINGENCIA_EXIGE_INDISPONIBILIDADE=true`. A exigência vem DESLIGADA por padrão: a contingência offline existe justamente para quando o PDV não fala com a SEFAZ, e o monitoramento (ciclo de 5 minutos) pode ainda não ter percebido a queda. | Emita normalmente (sem `contingencia: true`), ou peça ao responsável pela instalação para desligar `SEFAZ_CONTINGENCIA_EXIGE_INDISPONIBILIDADE`. `details.uf` traz a UF avaliada. | NFC-e | | `CRT2_SEM_REGIME_APURACAO` | `422` | Emissor do Simples Nacional com excesso de sublimite (`Issuer.crt = 2`, não MEI) sem `dpsNacional.regApTribSN`, em qualquer forma de emissão — `dpsNacional` ausente, parcial, com `opSimpNac`/`cTribNac`/`tribISSQN` completos ou com `resolverTributacao: true` (o Cérebro Fiscal também não tem fonte pra esse campo neste regime): o `crt` sozinho confirma que o emissor é optante do Simples, mas não diz o regime de apuração. | Informe `dpsNacional.regApTribSN` explicitamente. | NFS-e | | `CSC_AUSENTE` | `422` | Emissão de NFC-e por emissor não-sandbox sem CSC (Código de Segurança do Contribuinte) e ID do CSC configurados. | Configure o CSC e o ID do CSC em Dashboard → Emissores → (emissor) → aba NFCe antes de emitir. | NFC-e | | `CSOSN_CFOP_MEI_INCOMPATIVEL` | `422` | Emissor MEI (CRT=4) com `csosn: "102"` e CFOP fora da lista exigida (NF-e: 5102/6102; NFC-e: 5102). | Use um CFOP do domínio exigido para MEI com CSOSN 102. | NF-e, NFC-e | | `CSOSN_NAO_SUPORTADO` | `422` | CSOSN fora do domínio efetivo do (CRT, modelo) do emissor: elemento obrigatório do leiaute ausente do contrato, bloqueado por Regra de Validação, fora do domínio do emissor (ex.: MEI na NFC-e), ou código que não existe na Tabela CSOSN. | Use um CSOSN do domínio efetivo do emissor (ver `docs.engineapi.com.br/cobertura`) ou informe a tributação manualmente. | NF-e, NFC-e | | `CSOSN_REGIME_INCOMPATIVEL` | `422` | `icms.csosn` informado por um emissor de Regime Normal (CRT=3), que só admite `icms.cst`. | Use `icms.cst` para emissor de Regime Normal; CSOSN só vale para o Simples Nacional. | NF-e, NFC-e | | `CSOSN_VALORES_NAO_SUPORTADOS` | `422` | CSOSN aceito no domínio efetivo (102/103/300/400) acompanhado de `aliquota`/`baseCalculo`/`valor` — nenhum desses CSOSN tem campo para esses valores no leiaute. | Remova `aliquota`/`baseCalculo`/`valor` do item, ou use um CSOSN que os comporte (ex.: 101, 201, 202, 203, 500, 900). | NF-e, NFC-e | | `CST_NAO_SUPORTADO_NFE` | `422` | `icms.cst` (Regime Normal) fora do domínio que o motor resolve automaticamente hoje, e sem `icmsNormal` resolvido pelo Cérebro Fiscal. | Consulte a página de cobertura fiscal (`docs.engineapi.com.br/cobertura`) para o CST informado, ou use `resolverTributacao: true`. | NF-e | | `CST_REGIME_INCOMPATIVEL` | `422` | `icms.cst` (Regime Normal) informado por um emissor do Simples Nacional (CRT ≠ 3), que só admite CSOSN. | Use `icms.csosn` para emissor do Simples; `icms.cst` só vale para CRT=3 (Regime Normal). | NF-e, NFC-e | | `CTRIBMUN_CONFLITO` | `422` | `servico.codigoTributacaoMunicipio` e `dpsNacional.cTribMun` (mesmo campo do leiaute, `serv/cServ/cTribMun`) informados com valores diferentes. | Informe apenas um dos dois campos, ou os dois com o mesmo valor. | NFS-e | | `DESCONTO_INVALIDO` | `422` | `desconto` do item maior que o próprio valor do item, negativo, ou `ibsCbs.vBC` acima da base do item. | Corrija o valor de desconto do item — ele nunca pode zerar/negativar a base de cálculo. | NF-e, NFC-e | | `DEVOLUCAO_SEM_NITEM` | `422` | `finNFe: 4` (devolução) com item sem `documentoReferenciado.nItem`/`chaveAcesso` válidos — NT 2025.002-RTC, grupo VC: cada item da devolução referencia o `nItem` dele na nota original. | Informe `items[].documentoReferenciado: { chaveAcesso: "<44 dígitos>", nItem: <1..999> }` por item, ou deixe a API derivar por casamento de código de produto (cProd) quando a nota original for desta conta. | NF-e | | `DIFAL_INCOMPLETO` | `422` | Grupo `ICMSUFDest` informado pela metade — os seis campos obrigatórios do leiaute vêm juntos ou não vêm, incluindo o bloco de FCP da UF de destino. | Informe o grupo `ICMSUFDest` completo (base, alíquotas, partilha, valores e FCP quando houver). | NF-e, NFC-e | | `DIFAL_INVALIDO` | `422` | Grupo `ICMSUFDest` com alíquota interestadual fora de {4,7,12}, percentual de partilha diferente de 100 (vigente desde 2019), parcela do remetente ≠ 0 sob partilha integral, FCP incoerente, número fora do tipo, ou imposto > 0 sobre base zero. | Corrija o grupo `ICMSUFDest` conforme a mensagem de erro específica. | NF-e, NFC-e | | `DIFAL_NAO_APLICAVEL` | `422` | Grupo `ICMSUFDest` (DIFAL, EC 87/2015) informado numa operação que não é interestadual + consumidor final + destinatário não-contribuinte. | Remova o grupo `ICMSUFDest` quando a operação não for hipótese de partilha do DIFAL. | NF-e, NFC-e | | `FAIXA_INUTILIZACAO_MUITO_GRANDE` | `422` | Faixa de inutilização (`numInicial`..`numFinal`) maior que o limite por chamada — proteção contra saturação silenciosa de inteiro no processamento interno. | Divida a inutilização em chamadas menores, dentro do limite informado na mensagem. | NF-e, NFC-e | | `FINALIDADE_EXIGE_SEM_PAGAMENTO` | `422` | `finNFe` 3 (ajuste) ou 4 (devolução) com forma de pagamento diferente de "90" — o MOC exige "90" para essas duas finalidades (RV YA02-04). | Para `finNFe` 3 ou 4, use `pagamentos: [{ forma: "90", valor: 0 }]`. | NF-e | | `FINALIDADE_SEM_NFREF` | `422` | `finNFe` 2 (complementar), 3 (ajuste) ou 4 (devolução) sem `referenciadas[]` apontando a nota original — o leiaute pressupõe o grupo `NFref` para essas finalidades. | Informe `referenciadas: [{ chaveAcesso: "<44 dígitos da nota original>" }]`. | NF-e | | `FRETE_SEGURO_OUTRO_INVALIDO` | `422` | `valorFrete`/`valorSeguro`/`outrasDespesas` negativos, ou `indTot` fora de {0,1}. | Use valores não-negativos para frete/seguro/outras despesas, e `indTot` igual a 0 ou 1. | NF-e, NFC-e | | `IBPT_CITACAO_NAO_CABE` | `422` | Com a citação da fonte do IBPT, `informacoesComplementares` passaria dos 5.000 caracteres do leiaute (`infCpl`). | Reduza `informacoesComplementares`. O termo de uso do IBPT exige citar a fonte sempre que o valor é informado, então a engineAPI não escreve o valor sem a citação nem corta o seu texto. | NF-e, NFC-e | | `IBPT_INDISPONIVEL` | `422` | A tabela do IBPT não pôde ser consultada nesta emissão (fonte fora do ar, prazo esgotado ou credencial ausente), com a opção ligada no emissor. | Tente novamente em alguns minutos. Nenhum número fiscal foi consumido. Se persistir, desligue `valorAproximadoTributosEnabled` para emitir sem o valor. | NF-e, NFC-e | | `IBPT_NCM_AUSENTE` | `422` | Item sem NCM de 8 dígitos, com o valor aproximado dos tributos ligado no emissor — o valor é resolvido POR NCM. | Informe `items[].ncm` com os 8 dígitos, ou desligue a opção no cadastro da empresa. | NF-e, NFC-e | | `IBPT_NCM_SEM_TABELA` | `422` | A tabela do IBPT não tem linha para o NCM do item na UF do emissor, o emissor ligou o valor aproximado dos tributos (Lei 12.741/2012) e o modo ESTRITO está ligado no ambiente (`IBPT_BLOQUEAR_NCM_DESCONHECIDO=true`). No padrão, esse caso NÃO recusa: o documento é emitido sem o valor e sem a citação da fonte. | Confira o NCM do produto (o código precisa existir na NCM vigente) ou desligue `valorAproximadoTributosEnabled` no cadastro da empresa. A engineAPI não estima o valor sem fonte. | NF-e, NFC-e | | `IBPT_ORIGEM_INVALIDA` | `422` | `items[].icms.origem` fora de 0 a 8 (Tabela A do Ajuste SINIEF 15/13), com o valor aproximado dos tributos ligado no emissor. | Corrija a origem da mercadoria: ela decide qual percentual federal da tabela vale (nacional ou importado), e a engineAPI não presume "nacional" para origem desconhecida. | NF-e, NFC-e | | `IBPT_UF_EMISSOR_AUSENTE` | `422` | Cadastro do emissor sem UF, com o valor aproximado dos tributos ligado — a tabela do IBPT é estadual. | Complete a UF no cadastro da empresa ou desligue a opção. | NF-e, NFC-e | | `IBSCBS_CLASSE_SEM_RESOLVEDOR` | `422` | `ibsCbs.cClassTrib` informado sozinho (sem os percentuais do grupo) e sem `resolverTributacao`, que é quem desempata a classe multiclasse. | Informe o grupo `ibsCbs` completo manualmente, ou use `resolverTributacao: true` para o Cérebro Fiscal resolver os percentuais oficiais da classe. | NF-e, NFC-e | | `IBSCBS_DPS_DESTINATARIO_NAO_SUPORTADO` | `422` | `ibsCbs.indDest = "1"` (destinatário do serviço diferente do tomador) — o leiaute exige junto o grupo `dest` (CNPJ/CPF/NIF, nome, endereço), que este motor ainda não escreve. | Use `ibsCbs.indDest = "0"` quando o destinatário for o próprio tomador; para destinatário diferente, aguarde a cobertura do grupo `dest`. | NFS-e | | `ICMS_BENEFICIO_INCOMPLETO` | `422` | Grupo de benefício de ICMS (CST 20/40/41/50/51/90) informado pela metade — em especial desoneração sem `motDesICMS`/`indDeduzDeson`. | Informe o grupo de benefício completo, com o motivo da desoneração e o indicador de dedução quando aplicável. | NF-e, NFC-e | | `ICMS_BENEFICIO_INVALIDO` | `422` | Grupo de benefício informado de forma que o documento não representa: campo fora do CST que o comporta (ex.: `cBenefRBC` só existe no CST 51), motivo fora do conjunto do CST, número fora do tipo, ou valores que não fecham entre si. | Corrija o grupo de benefício conforme o CST informado. | NF-e, NFC-e | | `ICMS_BENEFICIO_NAO_SUPORTADO` | `422` | CST de benefício 50 (suspensão), 51 (diferimento) ou 90 ("outras") numa NFC-e (modelo 65) — a lista fechada de CST da NFC-e só admite 20, 40 e 41. | Não use CST 50/51/90 em NFC-e; use NF-e (modelo 55) para essas operações. | NFC-e | | `ICMS_MONOFASICO_INCOMPLETO` | `422` | Item declara CST monofásico 02/61 mas falta campo do grupo (`qBCMono`/`adRemICMS`/`vICMSMono` no 02; `qBCMonoRet`/`adRemICMSRet`/`vICMSMonoRet` no 61) — NT 2023.001. | Informe todos os campos do grupo monofásico exigidos pelo CST declarado. | NF-e, NFC-e | | `ICMS_MONOFASICO_INVALIDO` | `422` | Grupo monofásico informado de forma que o documento não representa: valor incoerente com quantidade × alíquota ad rem, campo errado para o CST, campo monofásico sem CST monofásico, mistura com ICMS clássico, ou CST 02 numa NFC-e. | Corrija o grupo monofásico conforme a mensagem de erro específica. | NF-e, NFC-e | | `ICMS_MONOFASICO_NAO_SUPORTADO` | `422` | CST monofásico 15 (própria com retenção) ou 53 (diferida) — existem no leiaute, mas a engineAPI ainda não emite. | Use um CST monofásico suportado (consulte `docs.engineapi.com.br/cobertura`) ou aguarde a cobertura desses CST. | NF-e, NFC-e | | `ICMS_MONOFASICO_SEM_COMBUSTIVEL` | `422` | CST monofásico sem o grupo `comb` no mesmo item — NT 2023.001, RV N12-100 (rejeição SEFAZ 959): sem `cProdANP` o produto não está na Tabela de Combustíveis Monofásicos. | Informe o grupo `comb` (com `cProdANP`) junto do CST monofásico. | NF-e, NFC-e | | `ICMS_REGIME_NORMAL_NAO_RESOLVIDO` | `422` | Emissor de Regime Normal (CRT=3) sem nenhum ICMS resolvido para o item (nem `icms.cst` manual, nem `icmsNormal` do Cérebro Fiscal). | Informe `icms.cst` manualmente ou use `resolverTributacao: true`. | NF-e, NFC-e | | `ICMS_RESIDUO_CONFLITA_ASSISTIDO` | `422` | Item pede resolução automática (`resolverTributacao: true`, sem `csosn`/`cst` manual) mas traz `icms.origem`/`icms.aliquota`/`icms.baseCalculo`/`icms.valor` preenchidos — campos que o CSOSN atribuído pelo Cérebro (102/103/300/400) não tem onde escrever. | Remova os campos residuais de `icms` do item, ou informe a tributação completa manualmente em vez de pedir resolução automática. | NF-e, NFC-e | | `ICMS_ST_INCOMPLETO` | `422` | Grupo `ICMS10`/`ICMS30`/`ICMS70` (ST desta operação) informado pela metade. | Informe o grupo de ST completo (modalidade da BC, base, alíquota, valor, e ICMS próprio quando o CST exigir). | NF-e, NFC-e | | `ICMS_ST_INVALIDO` | `422` | Grupo de ST desta operação informado de forma que o documento não representa: CST errado, CST de ST na NFC-e (proibido no leiaute), campo fora do grupo daquele CST, modalidade fora da enumeração, número fora do tipo, `vICMS` incoerente com `vBC × pICMS`, ou imposto > 0 sobre base zero. | Corrija o grupo de ST conforme a mensagem de erro específica. | NF-e, NFC-e | | `ICMS_ST_NAO_SUPORTADO` | `422` | Grupo de ICMS-ST do item usa um CST/modalidade fora do domínio que o motor escreve hoje. | Consulte `docs.engineapi.com.br/cobertura` para o CST de ST suportado. | NF-e, NFC-e | | `ICMS_ST_RETIDO_INCOMPLETO` | `422` | Grupo `ICMS60` (ST já retida — revenda) informado pela metade: o leiaute exige o bloco inteiro (base/alíquota/valor) ou nenhum. | Informe o grupo `ICMS60` completo, ou omita-o inteiramente. | NF-e, NFC-e | | `ICMS_ST_RETIDO_INVALIDO` | `422` | Grupo `ICMS60` informado de forma que o documento não representa: CST fora de "60", campo do grupo errado, CST 60 num modelo que não escreve o grupo (NFC-e), mistura com ICMS clássico/CSOSN, número fora do tipo do leiaute, ou imposto retido > 0 sobre base zero. | Corrija o grupo `ICMS60` conforme a mensagem de erro específica. | NF-e, NFC-e | | `INDFINAL_INCOERENTE_COM_DESTINATARIO` | `422` | `indFinal: 0` (não é consumidor final) com `destinatario.indicadorIE: 9` (ou destinatário CPF) — NT 2016.002 exige `indIEDest=9 ⇒ indFinal=1`. | Use `indFinal: 1` quando o destinatário for não-contribuinte (CPF ou IE=9), ou corrija `indicadorIE` se a operação for B2B. | NF-e, NFC-e | | `IPI_NAO_SUPORTADO` | `422` | `ipi` do item fora do domínio de CST que o motor escreve hoje. | Consulte `docs.engineapi.com.br/cobertura` para o CST de IPI suportado, ou omita o grupo. | NF-e, NFC-e | | `ISSUER_DIVERGENTE_NO_LOTE` | `422` | Uma nota do lote traz `issuerId` diferente do emissor do lote (raiz do corpo) — um lote emite por um único emissor. | Use o mesmo `issuerId` na raiz do lote e em cada nota (ou omita nas notas, herdando o do lote), e envie um lote por emissor. | NF-e | | `ITENS_AUSENTES` | `422` | Payload sem lista de itens utilizável (`items` ausente, `null`, objeto, ou array vazio) chegando pela fila. | Envie `items` como array com ao menos 1 item. | NF-e, NFC-e | | `JUSTIFICATIVA_CONTINGENCIA_INVALIDA` | `422` | `justificativaContingencia` fora da faixa de 15 a 256 caracteres na emissão de NFC-e. É o `xJust` do leiaute (tipo TJust), impresso no documento fiscal. O texto nunca é completado nem truncado, porque isso mudaria a declaração que o contribuinte faz ao fisco. | Envie uma justificativa entre 15 e 256 caracteres descrevendo o motivo real da contingência, ou omita o campo para usar a justificativa padrão de indisponibilidade. `details` traz `tamanho`, `minimo` e `maximo`. Nenhum número fiscal é consumido. | NFC-e | | `LGPD_CONSENT_REQUIRED` | `422` | Consulta de CPF (`GET /v1/queries/cpf/:cpf`) sem o header `X-LGPD-Consent: true` (Art. 7º LGPD). | Envie o header `X-LGPD-Consent: true` — só quando houver base legal (consentimento do titular) para a consulta. | Comum | | `LGPD_PURPOSE_REQUIRED` | `422` | Consulta de CPF sem o header `X-LGPD-Purpose`, ou com valor fora da lista aceita (Art. 6º LGPD). | Envie `X-LGPD-Purpose` com um dos valores aceitos: emissao\_nfe, cadastro, cobranca, obrigacao\_legal, contrato, credito. | Comum | | `LOTE_ACIMA_DO_LIMITE` | `422` | Lote de emissão em batch (`POST /v1/nfe/batch`) com mais notas do que o teto por chamada. | Divida o envio em lotes menores, dentro do limite informado em `details.maximoPorLote`. | NF-e | | `MUNICIPIO_NAO_ADERENTE_PADRAO_NACIONAL` | `422` | O município do emissor não adere ao Padrão Nacional da NFS-e neste ambiente: o espelho local já confirma `nao_aderente` (pré-voo, nenhum nDPS consumido) ou a SEFIN devolveu E0037 / "convênio não está ativo" depois da transmissão. | Cadastre o emissor em um município aderente neste ambiente, ou emita NF-e/NFC-e (que seguem disponíveis). No cadastro, `avisos[]` já traz este código quando a cobertura é `nao_aderente` confirmada. `details.mensagemSefin` preserva a mensagem original da SEFIN quando a recusa veio depois da transmissão. | NFS-e | | `NCM_MULTICLASSE` | `422` | Emissão assistida (`resolverTributacao: true`) de um item cujo NCM aparece em mais de um anexo da LC 214/2025 com tratamentos diferentes, e o payload não informou `items[].ibsCbs.cClassTrib`. O motor não escolhe sozinho: quem conhece o produto é quem emite. Depois de confirmada no cadastro do produto, a classe é reusada nas próximas emissões enquanto continuar entre as candidatas vigentes. | Consulte `details.itensNaoResolvidos[].candidatas` (nome, descrição, anexo e percentuais) e informe `items[].ibsCbs.cClassTrib`, ou confirme a classe uma vez em `POST /v1/fiscal/classification/classe` / no painel Cérebro Fiscal. Nada é emitido. | NF-e, NFC-e | | `PAGAMENTO_DIVERGENTE` | `422` | A soma de `pagamentos[].valor` não bate com o total da nota (`vNF`). | Corrija os valores de `pagamentos[]` até fecharem com o total da nota. Nada é emitido; nenhum número fiscal é consumido. | NF-e, NFC-e | | `PAGAMENTO_SEM_DADOS_DO_MEIO` | `422` | Forma de pagamento 03 (crédito), 04 (débito) ou 17 (PIX) sem o grupo `cartao` (ou com o grupo incompleto) — a SEFAZ exige o grupo para essas formas (RV YA04-10). | Informe `pagamentos[].cartao` completo para as formas 03/04/17, ou use outra forma de pagamento. | NF-e, NFC-e | | `PIS_NAO_SUPORTADO` | `422` | `pis` do item fora do domínio de CST que o motor escreve hoje. | Consulte `docs.engineapi.com.br/cobertura` para o CST de PIS suportado, ou omita o grupo. | NF-e, NFC-e | | `REFERENCIADA_INVALIDA` | `422` | `referenciadas[].chaveAcesso` fora de 44 dígitos, com UF/modelo inexistente na chave, dígito verificador que não fecha pelo módulo 11, ou chave repetida no array. | Confira a chave de acesso da nota referenciada (44 dígitos, dígito verificador válido). | NF-e | | `RETENCAO_ISS_CONFLITO` | `422` | `retencoes.issRetidoPor` e `dpsNacional.tpRetISSQN` (passthrough de baixo nível) declaram quem retém o ISS de forma diferente. | Informe apenas um dos dois campos (recomendado: `retencoes.issRetidoPor`), ou os dois com o mesmo valor. | NFS-e | | `RETENCAO_MAIOR_QUE_SERVICO` | `422` | Uma retenção federal (`retencoes.irrf`/`csll`/`inss`), ou a soma delas, é maior que `servico.valorServicos`. | Confira se o campo não recebeu a base de cálculo em vez do valor retido; a retenção é sempre uma parcela do serviço. | NFS-e | | `RETENCAO_PIS_COFINS_INCOERENTE` | `422` | `dpsNacional.tpRetPisCofins` e `retencoes.csll` se contradizem: o indicador diz que a CSLL não é retida mas veio valor, ou diz que é retida mas o valor está ausente/zerado. | Alinhe o indicador `tpRetPisCofins` (3, 7, 8 ou 9 incluem CSLL retida) com o valor de `retencoes.csll`. | NFS-e | | `RETENCAO_PIS_COFINS_SEM_CST` | `422` | `dpsNacional.tpRetPisCofins` informado sem `dpsNacional.cstPisCofins` — o grupo `piscofins` do leiaute exige o CST junto do indicador de retenção. | Informe `dpsNacional.cstPisCofins` junto do indicador `tpRetPisCofins`. | NFS-e | | `RETENCAO_PROVIDER_NAO_ESCREVE` | `422` | Retenção declarada numa emissão real (não-sandbox) pelo provider municipal/ABRASF, que não escreve retenção na DPS — só o provider ADN (Padrão Nacional) escreve. | Emita pelo Padrão Nacional (ADN) quando precisar declarar retenções, ou remova o bloco `retencoes`. | NFS-e | | `RETENCAO_SEM_CAMPO_NO_LEIAUTE` | `422` | `retencoes.pis`/`retencoes.cofins`/`retencoes.outrasRetencoes` informados — a DPS do Padrão Nacional não tem campo para o VALOR retido desses tributos (só INSS/IRRF/CSLL têm campo de valor). | Para PIS/COFINS, declare a retenção pelo indicador `dpsNacional.tpRetPisCofins` (junto de `dpsNacional.cstPisCofins`); remova os valores de `retencoes.pis`/`retencoes.cofins`/`retencoes.outrasRetencoes`. | NFS-e | | `RPS_SEM_CAMPO_NO_PADRAO_NACIONAL` | `422` | `rps` informado numa emissão real pelo provider ADN (Padrão Nacional) — o leiaute não tem campo para número/série de RPS; a própria DPS ocupa esse lugar. | Remova o campo `rps` do payload e guarde a correspondência pelo número da DPS devolvido na emissão. | NFS-e | | `SEM_PAGAMENTO_INVALIDO` | `422` | Forma de pagamento "90" (Sem Pagamento) usada com `valor` diferente de zero, combinada com outra forma no mesmo documento, ou gerando troco numa operação sem pagamento. | Use "90" sozinha e com `valor: 0`, ou informe a(s) forma(s) de pagamento reais sem misturar com "90". | NF-e, NFC-e | | `SEM_PAGAMENTO_VEDADO_NFCE` | `422` | Forma de pagamento "90" (Sem Pagamento) usada numa NFC-e (modelo 65) — vedação da SEFAZ (RV YA02-40): NFC-e registra venda com contraprestação. | Não use "90" na NFC-e. Operação sem pagamento (remessa, bonificação, comodato) é documento modelo 55 (NF-e). | NFC-e | | `SERIE_RESERVADA` | `422` | Série 890-899 (avulsa do Fisco) ou 900-999 (contingência), reservada no leiaute para uso distinto de emitente comum. | Use uma série de 0 a 889 para emissão comum. | NF-e, NFC-e | | `TOTAL_ACIMA_DO_LEIAUTE` | `422` | O somatório de algum total do grupo W não cabe no tipo do leiaute (13 dígitos inteiros e 2 decimais). | Reduza os valores dos itens/totais para caber no limite do leiaute (`TDec_1302`). | NF-e, NFC-e | | `TRIBUTACAO_NAO_RESOLVIDA` | `422` | Emissão com `resolverTributacao: true` (Cérebro Fiscal) e ao menos um item/campo do documento não foi resolvido automaticamente. Sub-motivos possíveis: UF sem regra de ICMS cadastrada; data de emissão anterior à vigência da regra; FCP condicionado a consumidor final com NCM fora da lista curada; `indFinal` ausente quando a UF exige; base de cálculo do ICMS que esta fase não modela; hipótese de DIFAL (EC 87/2015) fora do escopo desta fase (informe `items[].icms.ufDestino` manualmente); NCM multiclasse sem `ibsCbs.cClassTrib` desempatando; ou (NFS-e) ME/EPP no Simples sem `pTotTribSN` no payload nem `pTotTribSNPadrao` no cadastro do emissor. | Consulte `details.itensNaoResolvidos[]`/`details.documento[]`/`details.camposNaoResolvidos[]` — o motivo específico por item/campo — e informe a tributação manualmente ou cadastre a fonte que falta no emissor. | NF-e, NFC-e, NFS-e | | `UF_EMISSOR_INVALIDA` | `422` | Consulta de Distribuição DFe com `Issuer.state` ausente ou fora do domínio de UF — a consulta exige a UF do autor. | Cadastre a UF do emissor antes de consultar a Distribuição DFe. | Comum | | `UNIDADE_TRIBUTAVEL_INVALIDA` | `422` | A unidade tributável do item (`unidadeTributavel`/`quantidadeTributavel`/`valorUnitarioTributavel`) veio pela metade, não fecha com o valor do produto (`quantidadeTributavel × valorUnitarioTributavel` ≠ `quantidade × valorUnitario`), ou repete a unidade comercial com números diferentes. | Informe os três campos juntos e converta de forma que os dois lados deem o mesmo valor de produto; `valorUnitarioTributavel` aceita até 10 casas decimais para a conversão fechar. Para item sem conversão de unidade, omita os três. | NF-e, NFC-e | | `VNF_INVALIDO` | `422` | O total da nota (`vNF`) resultaria negativo, ou nenhum item compõe o total (`vNF=0` com mercadoria no documento). | Confira os valores de itens, frete, seguro, outras despesas e desconto — a soma tem que fechar num total não-negativo com pelo menos um item. | NF-e, NFC-e | Para o passo-a-passo com exemplos de alguns destes códigos, veja [Pré-voo do emissor](#pr-voo-do-emissor-422-quando-aparece), [Emissão assistida](#emisso-assistida-422-quando-aparece), [`finNFe` sem documento referenciado](#finnfe-2-3-ou-4-sem-o-documento-referenciado-422), [Documento referenciado inválido](#documento-referenciado-invlido-e-a-forma-sem-pagamento-422) e [Outros códigos de negócio](#outros-cdigos-de-negcio). `CNPJ_CONFLICT` sai com `code` e `message` **idênticos** nos dois casos (CNPJ seu ou de outro parceiro). A mensagem orienta `GET /v1/companies` e `POST /v1/companies/transfer-request` sem revelar o detentor (anti-oráculo, #383): a API nunca deixa um CNPJ de terceiro virar uma forma de descobrir se ele já tem emissor cadastrado em outro parceiro da plataforma, nem pela mensagem, nem pelo `code`. Estes slugs também pertencem ao catálogo público, mas ficam fora da tabela gerada de recusas de negócio. O Doc Contract compara esta lista com o registro que o filtro usa na saída. | Slug de `error.type` | HTTP | Quando ocorre | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------- | | `BAD_REQUEST`, `VALIDATION_ERROR` | `400` | Entrada inválida; `VALIDATION_ERROR` traz erros de campo em `error.errors[]` | | `UNAUTHORIZED`, `AMBIGUOUS_CREDENTIALS`, `IDENTITY_CONFLICT` | `401` | Credencial ausente ou inválida, ou credenciais e identidades em conflito | | `FORBIDDEN` | `403` | Acesso sem permissão | | `NOT_FOUND` | `404` | Recurso não encontrado | | `CONFLICT` | `409` | Conflito de estado do recurso | | `PAYLOAD_TOO_LARGE` | `413` | Upload ou corpo JSON acima do limite; divida o envio conforme `error.details` | | `UNPROCESSABLE_ENTITY` | `422` | Recusa local sem código de negócio mais específico | | `RATE_LIMIT_EXCEEDED`, `TOO_MANY_REQUESTS` | `429` | Limite do plano ou do provedor externo de consulta | | `INTERNAL_ERROR`, `INTERNAL_SERVER_ERROR` | `500` | Falha interna; informe `error.requestId` ao suporte | | `MANIFESTACAO_NAO_DISPONIVEL` | `501` | Manifestação DFe ainda não implementada no provider real | | `BAD_GATEWAY`, `CNPJA_RESPOSTA_INVALIDA` | `502` | Provedor externo retornou uma resposta inválida ou falhou | | `SERVICE_UNAVAILABLE`, `CNPJA_INDISPONIVEL`, `CNPJA_FILA_INDISPONIVEL`, `CNPJA_NAO_CONFIGURADA`, `CNPJA_SALDO_INSUFICIENTE`, `CNPJA_RATE_LIMIT`, `DFE_PROVIDER_MOCK`, `DFE_CONSUMO_INDEVIDO`, `DFE_INTERVALO_MINIMO`, `DFE_CICLO_EM_ANDAMENTO` | `503` | Dependência, consulta cadastral ou Distribuição DFe indisponível; consulte `error.detail` antes de repetir | | `RECUSA_NAO_CATALOGADA` | Mesmo HTTP da recusa original | O filtro substituiu um código não registrado; informe `error.requestId` ao suporte | `EMISSOR_INEXISTENTE` é um desfecho `FAILED` da fila, em `resultData.error`. Ele não é um slug de resposta HTTP: o emissor foi removido depois do enfileiramento e nenhum número fiscal foi consumido. Os erros de consulta externa (`GET /v1/queries/cnpj/:cnpj` e `GET /v1/queries/cpf/:cpf`, Receita Federal/SerPro) que **não** batem com nenhum `code` de negócio caem nos slugs genéricos por status: `NOT_FOUND` (CNPJ/CPF não encontrado), `BAD_GATEWAY` (falha sem categoria mais específica) ou `SERVICE_UNAVAILABLE` (provedor fora do ar). *** ## Rejeição SEFAZ/SEFIN (400): exemplos Independente do módulo (NF-e, NFC-e, NFS-e), a rejeição fiscal chega como `400` com `error.erros[]`. Alguns códigos comuns: | Código | Mensagem SEFAZ | Causa | Solução | | ------ | ----------------------------- | ----------------------------------------- | ------------------------------------------------ | | `204` | CNPJ do emitente inválido | Dígito verificador errado | Valide o CNPJ com algoritmo módulo 11 | | `206` | IE do emitente inválida | IE não corresponde ao estado | Verifique a IE com a SEFAZ estadual | | `225` | Código NCM inválido | NCM com menos de 8 dígitos ou inexistente | Consulte a [tabela NCM](/conceitos/cfop-ncm-cst) | | `539` | Duplicidade de NF-e | Nota com mesmo número e série já existe | Incremente o número da nota | | `591` | CNPJ do destinatário inválido | Dígito verificador errado | Valide o CNPJ do cliente | | Código | Mensagem SEFAZ | Causa | Solução | | ------ | ---------------------------------------------- | --------------------------------- | ---------------------------------------- | | `280` | Certificado Transmissor inválido | Certificado expirado ou incorreto | Renove o certificado A1 | | `281` | Certificado Transmissor vencido | Validade expirada | Faça upload de novo certificado | | `283` | CNPJ-Base do Certificado Transmissor diferente | Certificado de outro CNPJ | Use o certificado correto para esse CNPJ | | Código | Mensagem SEFAZ | Causa | Solução | | ------ | ----------------------------------------------------- | --------------------------------------------- | ---------------------------------------------- | | `298` | Soma dos valores do pagamento difere do total da NF-e | Soma de `pagamentos[].valor` ≠ soma dos itens | Verifique os cálculos | | `571` | Total do ICMS diverge do somatório do ICMS dos itens | Soma ICMS incorreta | Recalcule com alíquota × base | | `613` | CFOP de entrada não permitido para saída | CFOP iniciando com 1 ou 2 para saída | Use CFOP com 5 (estadual) ou 6 (interestadual) | | Código | Mensagem SEFAZ | Causa | Solução | | ------ | ---------------------------------- | ------------------------- | ---------------------------------------------- | | `108` | Serviço Paralisado Momentaneamente | SEFAZ estadual fora do ar | Aguarde e tente novamente em 5 minutos | | `109` | Serviço Paralisado sem Previsão | Manutenção SEFAZ | Consulte o [status da SEFAZ](/conceitos/sefaz) | | `999` | Rejeição: erro não catalogado | Erro interno SEFAZ | Tente novamente; se persistir, contate suporte | | Código | Mensagem SEFAZ | Causa | Solução | | ------ | ------------------------------------ | -------------------------------------------- | -------------------------------------------- | | `210` | IE do Destinatário inválida | IE não corresponde ao estado do destinatário | Verifique a IE com a UF | | `243` | UF do Destinatário não existe | Código de estado inválido | Use a sigla de 2 letras: `SP`, `RJ`, `MG`... | | `244` | Município do Destinatário não existe | `codigoMunicipio` inválido | Consulte a tabela IBGE de municípios | | Código | Mensagem SEFAZ | Causa | Solução | | ------ | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `501` | Rejeicao: Prazo de cancelamento superior ao previsto na Legislacao | Cancelamento solicitado após o prazo da UF. NFC-e (mod. 65): 30 min, padrão nacional (Ajuste SINIEF 07/18), em GO art. 167-S-Q do RCTE-GO; NF-e (mod. 55): 24h | Não há cancelamento extemporâneo via API. O remédio legal é emitir uma **NF-e de devolução** com `finNFe: 4`, `referenciadas` e `pagamentos: [{ "forma": "90", "valor": 0 }]`; a API valida esses requisitos antes de numerar. A nota original permanece `AUTHORIZED`. Este cStat é repassado verbatim no corpo `400` (`error.erros[]`), ver [Emissão de NF-e](/guides/emitir-nfe#tratamento-de-erros) | ***

Emissão assistida (422): quando aparece

Só ocorre com `resolverTributacao: true` no payload de NF-e/NFC-e/NFS-e. Se um campo fiscal obrigatório (ex.: CSOSN, grupo IBS/CBS, `cTribNac`) não tiver fonte para ser resolvido pelo Cérebro Fiscal, a API responde **422** e **nada é emitido/persistido**: ```json theme={null} { "error": { "type": "https://engineapi.com.br/errors/TRIBUTACAO_NAO_RESOLVIDA", "title": "Entidade Não Processável", "status": 422, "detail": "Tributação assistida: 2 item(ns) não resolvidos. Nada foi emitido. Corrija os itens ou informe a tributação (csosn/ibsCbs) manualmente.", "instance": "/v1/nfe", "requestId": "req_abc123", "timestamp": "2026-07-06T12:00:00.000Z" } } ``` Na NF-e/NFC-e, o corpo real inclui `{index, motivo}` por item não-resolvido; na NFS-e, `camposNaoResolvidos` com `{campo, motivo}`. Corrija o cadastro do emissor (`servicoPadraoLc116`/`cTribNacPadrao`) ou informe o campo manualmente, e reenvie.

Espelho fiscal divergente

Um dos motivos possíveis dentro de `details.itensNaoResolvidos`: a redução de IBS/CBS que temos espelhada para o NCM **não bate com a tabela oficial de classificação tributária** para a classe (`cClassTrib`) daquele mesmo NCM. Recusamos com este `422` **antes** de transmitir: a SEFAZ rejeitaria a mesma incoerência com `cStat` `1034`/`1046`/`1063` (IBS-UF/IBS-Municipal/CBS), só que sem contexto nenhum. Como seguir agora: informe o grupo `ibsCbs` do item explicitamente (override do parceiro, o motor não recalcula nem consulta o espelho para ele), ou emita esse item **sem** `resolverTributacao`, com a tributação que o seu ERP já tem. Exemplo de payload, o motivo completo de recusar antes de transmitir, e como um mesmo NCM pode ter mais de um anexo de redução: [Erros de IBS/CBS](/guides/errors-ibs-cbs#espelho-fiscal-divergente).

NCM multiclasse

Outro motivo dentro de `details.itensNaoResolvidos`, e o mais comum em alimento: o NCM aparece em **mais de um anexo da LC 214/2025**, com percentuais diferentes. Quem decide qual vale é o produto real, não o código: a resposta traz `candidatas[]` com todas as classes vigentes; informe `ibsCbs.cClassTrib` para desempatar. Exemplo completo de payload/resposta, a tabela dos 4 `code`s irmãos (`NCM_MULTICLASSE`, `NCM_SEM_CLASSE_AUTOMATICA`, `CCLASSTRIB_INVALIDO_PARA_NCM`, `CCLASSTRIB_INADMISSIVEL_NO_MODELO`) e as três regras de informar só a classe: [Erros de IBS/CBS](/guides/errors-ibs-cbs#ncm-multiclasse). ***

Pré-voo do emissor (422): quando aparece

Antes de acionar o worker de emissão, a engineAPI valida se o **cadastro do emissor** (NF-e e NFC-e, o mesmo cadastro) tem o que o documento fiscal exige. Duas checagens, mesmo contrato de resposta: ```json theme={null} { "error": { "type": "https://engineapi.com.br/errors/CERTIFICADO_AUSENTE", "title": "Entidade Não Processável", "status": 422, "detail": "Certificado A1 não instalado para o emissor \"Padaria Teste LTDA\". Instale o certificado em Certificados antes de emitir.", "instance": "/v1/nfe", "requestId": "req_abc123", "timestamp": "2026-07-15T18:13:00.000Z" } } ``` Faça upload do certificado A1 em **Certificados** no dashboard e reenvie. Campos exigidos pelo XML da NF-e/NFC-e que o cadastro do emissor pode deixar vazio: **IE** (número de 2 a 14 dígitos ou a string `"ISENTO"`, em MAIÚSCULAS, o pattern da SEFAZ é case-sensitive) e **endereço completo** (logradouro, bairro, município, UF, CEP). Sem eles, o schema local do motor fiscal reprovaria a nota; a engineAPI barra ANTES, com a lista exata do que falta: ```json theme={null} { "error": { "type": "https://engineapi.com.br/errors/CADASTRO_EMISSOR_INCOMPLETO", "title": "Entidade Não Processável", "status": 422, "detail": "Cadastro do emissor \"Padaria Teste LTDA\" está incompleto para emissão: Inscrição Estadual (IE): informe o número (2 a 14 dígitos) ou \"ISENTO\" (maiúsculas). Complete o cadastro em Empresas antes de emitir.", "details": { "issuerId": "3fa85f64-...-uuid", "camposFaltando": ["ie"] }, "instance": "/v1/nfe", "requestId": "req_014f0277f6ad", "timestamp": "2026-07-15T18:13:00.000Z" } } ``` Complete o campo faltante em **Empresas** e reenvie. `camposFaltando[]` lista TODOS os campos ausentes de uma vez (não corrige um por vez). O mesmo pré-voo protege a **fila de emissão** (`POST /v1/nfe/batch`): o item falha como `FAILED` permanente (sem retry, retry não completa cadastro) com este mesmo envelope em `resultData.error`, e **nenhum número da sequência fiscal é consumido**. Exclusivo da NFC-e (modelo 65): fora do ambiente sandbox, `csc` (o token) e `cscId` (o ID do token) precisam estar cadastrados no emissor: ```json theme={null} { "error": { "type": "https://engineapi.com.br/errors/CSC_AUSENTE", "title": "Entidade Não Processável", "status": 422, "detail": "CSC (Código de Segurança do Contribuinte) não configurado para o emissor \"Padaria Teste LTDA\". Configure o CSC e o ID do CSC em Dashboard → Emissores → (selecione o emissor) → aba NFCe antes de emitir.", "details": { "issuerId": "3fa85f64-...-uuid" }, "instance": "/v1/nfce", "requestId": "req_abc123", "timestamp": "2026-07-30T18:13:00.000Z" } } ``` Gere/consulte o CSC no portal da SEFAZ do seu estado (Contribuinte → NFC-e → Autorização de Uso do CSC), cadastre em **Dashboard → Emissores → aba NFC-e** e reenvie. Emissor sandbox (toda conta nova nasce assim) emite normalmente sem CSC, só passa a ser exigido ao trocar para o ambiente Produção. ***

Outros códigos de negócio

`POST /v1/nfe` e `POST /v1/nfce` aceitam `numero` explícito no payload (passthrough). Se aquele número (na mesma série e modelo do emissor) já foi usado por outro documento, a resposta é `409` com `code: NUMERO_JA_UTILIZADO`: a mensagem diz o número/série/modelo em conflito e os dois caminhos: usar outro número, ou **omitir o campo `numero`** para a numeração automática do emissor (recomendado, o motor mantém a sequência fiscal atômica por emissor+série). Nada é emitido e nenhum número novo é consumido. `POST /v1/nfe` e `POST /v1/nfce` com `pagamentos[].forma` `"03"` (crédito), `"04"` (débito) ou `"17"` (PIX) exigem o grupo `pagamentos[].cartao` com ao menos `tpIntegra` (`1` integrado ou `2` não integrado). Sem ele, ou com `tpIntegra=1` sem `cnpjInstituicao`, a SEFAZ rejeita com **391** depois de consumir o número fiscal (NT 2023.004 v1.11, RV YA04-10; GO aplica). A API recusa **antes** com `422` e `code: PAGAMENTO_SEM_DADOS_DO_MEIO`. PIX estático (chave copia-e-cola) usa `{ "tpIntegra": 2 }`; CNPJ da credenciadora, bandeira e autorização são opcionais. Na emissão de NF-e/NFC-e, a soma de `pagamentos[].valor` menos `troco` (se houver) precisa bater **no centavo** com o total dos itens (a mesma conta do `vNF` transmitido: soma dos `vProd` já arredondados a 2 casas). Divergência devolve `422` com `code: PAGAMENTO_DIVERGENTE`, citando os dois valores, antes de qualquer chamada à SEFAZ e sem consumir número fiscal. **Com `desconto` nos itens, o total esperado é o LÍQUIDO** (`vNF = produtos − desconto + IPI`): o desconto agora vai no documento, então pagar o valor bruto é divergência de verdade. Antes o motor aceitava os dois valores porque o desconto era ignorado na emissão; hoje não é mais. **Com `valorFrete`/`valorSeguro`/`outrasDespesas` nos itens, eles SOMAM ao total** (`vNF = produtos − desconto + valorFrete + valorSeguro + outrasDespesas + IPI`), o inverso do desconto. Não existe tolerância "sem os acessórios": se você informa frete no item, o pagamento tem que cobri-lo. `items[].desconto` é o **desconto incondicional** do item, em reais, o `vDesc` do leiaute. Ele vai para o documento (no item e no total), reduz o `vNF` e reduz a **base de cálculo** do ICMS e do IBS/CBS (LC 87/1996 art. 13, § 1º, II, "a"; LC 214/2025 art. 12, § 2º, III). Devolve `422` com `code: DESCONTO_INVALIDO`, antes de qualquer chamada à SEFAZ e sem consumir número fiscal, quando: | Situação | Por quê | | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `desconto` **maior** que o valor do item (`quantidade × valorUnitario`) | base de cálculo e total da nota ficariam negativos. Se o desconto é do pedido inteiro, distribua entre os itens | | `desconto` **negativo** | o campo é redutor; um negativo seria acréscimo e aumentaria a base do imposto em silêncio (também barrado antes, com `400`, pela validação de schema) | | `ibsCbs.vBC` informado **maior** que `vProd − desconto` | o `vBC` explícito vence o valor calculado, então o IBS/CBS sairia sobre base maior que o valor da operação. Omita o campo para o motor usar a base correta | `desconto` igual ao valor do item é **aceito** (item integralmente descontado: base 0, imposto 0). Desconto **condicional** (o que depende de evento posterior, como pagamento antecipado) **não deve** ser informado aqui: por lei ele integra a base de cálculo, e o leiaute do item não tem campo para ele. A recusa vale igual **com e sem** `resolverTributacao: true`, e nos dois caminhos de emissão (síncrono e lote); em nenhum deles o número fiscal é consumido. No **sandbox**, o XML de demonstração sai com os mesmos valores que a produção transmitiria (`vDesc` no item, `vNF` líquido): o que você testa é o que a SEFAZ receberia. `cobranca.fatura` e `cobranca.duplicatas[]` (venda a prazo, [Guia: Venda a prazo](/guides/venda-a-prazo)) passam por 5 conferências antes de qualquer chamada à SEFAZ, todas com `code: COBRANCA_INVALIDA`: | Situação | Regra | | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `fatura.valorDesconto` maior que `fatura.valorOriginal` | grupo Y do leiaute (Y04/Y05) | | `fatura.valorLiquido` diferente de `valorOriginal − valorDesconto` | grupo Y (Y04/Y05/Y06), igualdade EXATA sobre o valor de 2 casas | | Soma de `duplicatas[].valor` diferente do líquido da fatura, quando os dois vêm juntos | grupo Y (Y10) | | `vencimento` anterior à data de emissão, ou anterior ao vencimento da parcela anterior | grupo Y (Y09): duplicatas precisam vir em ordem não-decrescente | | `duplicatas` enviada sem `fatura` | grupo Y (Y10-bis, #930): MOC 7.0 Anexo I torna a combinação inválida (Y01-20/Y10-10) — recusa local, antes de numerar | **Fila (`POST /v1/nfe/batch`): uma nota pode ficar válida quando enfileirada e recusada quando processada, sem o payload ter mudado.** `vencimento >= hoje` é conferido no momento em que o item roda o pré-voo, não no momento em que você enfileirou. Uma nota parada na fila (emissor sem certificado, atraso do worker) até depois da data de `vencimento` recusa no processamento: não é um payload ruim, é o tempo passando por baixo dele. Nesse caso específico, reenviar com a MESMA data de vencimento repete a recusa (ela só piora com o tempo); ajuste `vencimento` para uma data futura e reenvie. `items[].valorFrete`, `items[].valorSeguro` e `items[].outrasDespesas` são `vFrete`/`vSeg`/`vOutro` do leiaute, em reais. Ao contrário do `desconto`, são campos **aditivos**: vão para o documento (no item e no total), aumentam o `vNF` e aumentam a **base de cálculo** do ICMS e do IBS/CBS, o mesmo mecanismo do desconto em sentido inverso (LC 87/1996 art. 13, § 1º, II, "a"/"b"; LC 214/2025 art. 12, § 1º, III). `items[].indTot` indica se o `vProd` do item entra no `vProd`/`vNF` do total da nota: `1` (ausente = `1`, default do leiaute) compõe; `0` não compõe. Não muda a tributação do próprio item, só a composição do total. **Na NFC-e só `1` é aceito** (ver tabela abaixo). Devolve `422` com `code: FRETE_SEGURO_OUTRO_INVALIDO`, antes de qualquer chamada à SEFAZ e sem consumir número fiscal, quando: | Situação | Por quê | | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `valorFrete`/`valorSeguro`/`outrasDespesas` **negativo** | os três campos são aditivos por definição do leiaute (só somam); um negativo seria um desconto disfarçado. Use o campo `desconto` para reduzir o valor do item (também barrado antes, com `400`, pela validação de schema) | | `indTot` fora de `{0, 1}` | o leiaute só define os dois valores (também barrado antes, com `400`, pela validação de schema) | | `indTot: 0` na **NFC-e** (modelo 65), mesmo sozinho | o leiaute rejeita item que não participa do total nesse modelo (MOC 7.0 Anexo I, RV I17b-10); o Zod já restringe a `1` (`400`), isto cobre payload cru | | `indTot: 0` combinado com `desconto`/`valorFrete`/`valorSeguro`/`outrasDespesas` **no mesmo item** | o item some do `vProd` do total, mas esses campos continuam somando/subtraindo do `vNF`: o total pode sair negativo ou divergente do valor real da mercadoria (ver `VNF_INVALIDO` abaixo) | | `transporte.modFrete` é `1` (destinatário), `2` (terceiros) ou `4` (transporte próprio do destinatário) e o item traz `valorFrete > 0` | frete só integra a base do ICMS quando é o próprio remetente que paga o transporte, seja contratado (CIF, `modFrete: 0`) seja com frota própria (`modFrete: 3`), conforme LC 87/1996 art. 13, § 1º, II, "b". Frete por conta do destinatário não se informa em `valorFrete` | | `valorFrete` em **qualquer item da NFC-e** (modelo 65) | a NFC-e sempre emite como venda presencial, sem transporte; frete pressupõe entrega a domicílio, cenário que a NFC-e ainda não representa. Emita uma NF-e (modelo 55) para documentos com frete | Pode informar `desconto` e `valorFrete`/`valorSeguro`/`outrasDespesas` no **mesmo item** (sem `indTot: 0`): a base de cálculo aplica os dois eixos juntos (`vProd − desconto + valorFrete + valorSeguro + outrasDespesas`). Duas recusas de sanidade do `[Total].vNF`, sempre ANTES de qualquer chamada à SEFAZ e sem consumir número fiscal: | Situação | Por quê | | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | Nenhum item da nota compõe o total (`indTot: 0` em todos) | o documento sairia assinado com `vNF=0.00` mesmo com mercadoria de valor real dentro | | `vNF` calculado (produtos + IPI + frete/seguro/outras despesas − desconto) é **negativo** | nenhum campo monetário do leiaute aceita valor negativo; é sempre payload inválido, nunca um caso de negócio | Na prática, o guard por item de `FRETE_SEGURO_OUTRO_INVALIDO` (acima) já impede a maioria dos casos que levariam a um `vNF` negativo: este código é a rede de trás, para o caso de nenhum item compor o total. Todo grupo tributário que você envia ou **vai para o documento**, ou é recusado com `422` antes de qualquer chamada à SEFAZ (nenhum número fiscal é consumido). Os valores informados de PIS/COFINS/IPI são transmitidos como vieram: o motor é passthrough e não calcula tributo. | Situação | `code` | | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | Valores de PIS/COFINS sem `cst`, ou `cst` fora da tabela do leiaute | `PIS_NAO_SUPORTADO` / `COFINS_NAO_SUPORTADO` | | `cst` tributado (`01`/`02`) sem `baseCalculo` + `aliquota` + `valor` | `PIS_NAO_SUPORTADO` / `COFINS_NAO_SUPORTADO` | | Valores em `cst` NÃO tributado (`04`–`09`), o documento carrega só o CST | `PIS_NAO_SUPORTADO` / `COFINS_NAO_SUPORTADO` | | `cst` `03` (tributação por quantidade) | `PIS_NAO_SUPORTADO` / `COFINS_NAO_SUPORTADO` | | `ipi` sem `cst`, `cst` tributado sem os valores, ou valores em CST não tributado | `IPI_NAO_SUPORTADO` | | `ipi` numa **NFC-e** (o modelo 65 não tem IPI no leiaute) | `IPI_NAO_SUPORTADO` | | `cest` fora de 7 dígitos (ex.: com pontos) | `CEST_INVALIDO` | | ICMS-ST nos campos antigos (`icms.baseCalculoST`/`aliquotaST`/`valorST`), sem efeito no documento | `ICMS_ST_NAO_SUPORTADO` | | Campo de ST **já retida** (`vBCSTRet`, `pST`, `vICMSSTRet`...) sem `icms.cst: "60"`, na NF-e | `ICMS_ST_RETIDO_INVALIDO` | | Campo de ST **desta operação** (`modBCST`, `vBCST`, `pICMSST`, `vICMSST`...) sem `icms.cst` `"10"`/`"30"`/`"70"` | `ICMS_ST_INVALIDO` | | Bloco da ST desta operação pela metade | `ICMS_ST_INCOMPLETO` | `valor: 0` (zero explícito) **não** é erro em nenhum desses grupos, inclusive ICMS-ST e `ipi: {}`: o documento sai igual ao padrão zerado. Formatação também não é motivo de recusa: `cst` de 1 dígito vira 2 (`"1"` → `"01"`) e `cest` com máscara é normalizado. Atenção ao IPI: ele **compõe o total da nota** (`vNF = produtos + IPI`). Para `pagamentos`, aceitamos tanto o total dos produtos quanto produtos + IPI: só o que não bate com nenhum dos dois devolve `422 PAGAMENTO_DIVERGENTE`. O `desconto` dos itens, quando houver, é descontado dos **dois** valores (o documento sai pelo líquido). Os mesmos `422` valem no **lote** (`POST /v1/nfe/batch`): o item da fila falha no pré-voo, antes de consumir número fiscal, e sai como `FAILED` com o `code`, sem retry (payload não muda entre tentativas). O bloco ICMS do item precisa ser coerente com o regime tributário do emissor (`crt` do cadastro): | Situação | `code` | | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Emissor Simples Nacional (CRT=1) ou MEI (CRT=4) com `icms.cst` e sem `csosn` (inclusive CST `00` com `modBC`/`vBC`/`pICMS`/`vICMS`) | `CST_REGIME_INCOMPATIVEL`, Simples usa `csosn` (ex.: `102`) | | Emissor Regime Normal (CRT=3) com `icms.csosn` | `CSOSN_REGIME_INCOMPATIVEL`, Regime Normal usa `cst` | | Emissor Regime Normal (CRT=3) com `icms.cst` informado à mão (CST **não** indica ST) | `CST_NAO_SUPORTADO_NFE`, o grupo de ICMS do leiaute exige a modalidade da base de cálculo (`modBC`), que não faz parte deste contrato; use `"resolverTributacao": true` (hoje a fase Normal só emite CST `00`) | | Emissor Regime Normal (CRT=3) com `icms.cst` `10`/`30`/`60`/`70` (indica substituição tributária) | `CST_NAO_SUPORTADO_NFE`, mas **sem** sugerir `resolverTributacao`: ICMS-ST não é suportado nesta fase em nenhum dos dois caminhos (manual ou assistido) | | Emissor Regime Normal (CRT=3) **sem ICMS e sem** `resolverTributacao` | `ICMS_REGIME_NORMAL_NAO_RESOLVIDO`, sem isso o documento sairia com CSOSN (código exclusivo do Simples) e a SEFAZ o rejeitaria | | Emissor CRT=2 (Simples com excesso de sublimite de receita bruta) com `icms.csosn` | `CSOSN_REGIME_INCOMPATIVEL`. A NT 2024.001 tira este sub-regime da família CSOSN para efeito de ICMS: usa `cst`, como o Regime Normal (a SEFAZ rejeita CSOSN neste CRT com `591`) | | Emissor Simples/MEI com `icms.csosn` fora do domínio do seu `crt` e do modelo do documento | `CSOSN_NAO_SUPORTADO`, ver tabela de domínio efetivo abaixo | Todos são `422` locais: nada chega à SEFAZ e nenhum número fiscal é consumido. ### Domínio efetivo de CSOSN, por (crt, modelo) O motor não aceita todo código da Tabela CSOSN: só os que emite um documento correto de ponta a ponta, e isso depende do **regime** (`crt`) e do **documento** (NF-e ou NFC-e), não é uma lista única: | `crt` | NF-e | NFC-e | | --------------------------------- | --------------------------------------------------------------------------- | ---------------------------------- | | 1 (Simples Nacional) | `102`, `103`, `300`, `400`, `201`, `202`, `203` | `102`, `103`, `300`, `400` | | 4 (MEI) | `102`, `300`, `400` (sem `103`: MEI não tem faixa de receita bruta gradual) | `102`, `300` (mais restrito ainda) | | 2 (Simples, excesso de sublimite) | usa `cst`, não `csosn` (ver linha da tabela acima) | idem | | 3 (Regime Normal) | usa `cst`, não `csosn` | idem | **`201`, `202` e `203` (substituição tributária cobrada nesta operação) emitem na NF-e do Simples Nacional pleno (`crt: 1`).** Você informa o grupo inteiro: `modBCST`, `vBCST`, `pICMSST` e `vICMSST` (mais `pMVAST` e `pRedBCST`, opcionais, e o trio `vBCFCPST`/`pFCPST`/`vFCPST`, indivisível). O `201` exige também `pCredSN` e `vCredICMSSN`, o crédito do artigo 23 da LC 123/2006, que sai da sua apuração. O motor transcreve e valida: não estima margem nem alíquota interna de ST, e não calcula o crédito. Grupo incompleto recusa com `422 ICMS_ST_INCOMPLETO`; campo que o código não comporta (ICMS próprio, `cst` junto do `csosn`) recusa com `422 ICMS_ST_INVALIDO`. **`pCredSN` e `vCredICMSSN` só têm lugar no `201`**: informá-los em qualquer outro código (um `202`/`203`, um `102`, ou um `icms.cst` de Regime Normal) recusa com `422 ICMS_ST_INVALIDO` em vez de emitir sem eles. O leiaute não tem onde escrevê-los fora do grupo `ICMSSN201`, e uma nota autorizada sem o crédito que você informou é um crédito que o adquirente perde sem aviso. Na **NFC-e** os três continuam fora: a regra de validação que lista os CSOSN aceitos no modelo 65 não traz os códigos de ST, então emita uma NF-e para essa operação. No **MEI** também não: o domínio de CSOSN do MEI é mais estreito e não foi auditado para ST. `101` (crédito) não emite em nenhum `crt`/modelo hoje: o leiaute exige `pCredSN`/`vCredICMSSN` num grupo que este contrato ainda não escreve, e emitir sem eles violaria o leiaute. `500` (ICMS já cobrado por ST/antecipação) e `900` (categoria residual) **são válidos na forma do leiaute**, mas a Regra de Validação da NT 2024.001 (MOC 7.0, Anexo I) exige mais do que a forma: `500` precisa do CEST do produto e, na NFC-e, de um CFOP específico de retorno de ST; `900` depende do destinatário e do modelo de um jeito que o motor ainda não resolve sozinho. Emitir sem essas informações arriscaria um documento tecnicamente válido mas faticamente errado: a mesma régua "ST nunca chuta, recusa" do Regime Normal. Os dois recusam com `422 CSOSN_NAO_SUPORTADO` hoje. **MEI (`crt: 4`) com `csosn: "102"` exige CFOP específico**: NF-e só `5102` ou `6102`; NFC-e só `5102`. Fora disso, `422 CSOSN_CFOP_MEI_INCOMPATIVEL` (a SEFAZ rejeitaria a combinação com `337`). CFOP ausente usa o padrão `5102`, dentro do domínio. Mesmo dentro do domínio da tabela acima, a NFC-e do Simples "pleno" (`crt: 1`) com `csosn` `103` ou `400` pode ser rejeitada pela SEFAZ da UF do emitente conforme a legislação estadual: a API não bloqueia esse caso hoje (não é regra federal única, varia por UF), mas avisa: teste na UF do seu emissor antes de ir a produção com esses códigos na NFC-e. **Regime Normal emite**: veja o guia [Regime Normal (Lucro Real/Presumido)](/guides/regime-normal). O ICMS é calculado pelo motor fiscal a partir de uma base auditada, e o que ele não cobre recusa com `422 TRIBUTACAO_NAO_RESOLVIDA` e motivo por item, inclusive **produto sujeito a substituição tributária**, detectado pelo NCM (CEST do Convênio 142/2018) antes de qualquer cálculo. **Nesta fase (N1), o motor calcula o CST `00`** (tributação integral). ST, benefícios fiscais e DIFAL têm caminhos manuais próprios: quem emite informa os valores, e a API valida e transmite os grupos aplicáveis. Fora desses caminhos, `"cst"` manual e `"resolverTributacao": true` recusam com motivo específico. Confira o que está coberto hoje em [Cobertura Fiscal](/cobertura). `GET /v1/queries/cpf/:cpf` exige dois headers de compliance LGPD antes de consultar a Receita Federal (via SerPro). Sem `X-LGPD-Consent: true`: ```json theme={null} { "error": { "type": "https://engineapi.com.br/errors/LGPD_CONSENT_REQUIRED", "title": "Entidade Não Processável", "status": 422, "detail": "Header X-LGPD-Consent é obrigatório e deve ser \"true\". Art. 7° LGPD: tratamento de dados pessoais requer base legal.", "instance": "/v1/queries/cpf/12345678900", "requestId": "req_abc123", "timestamp": "2026-07-20T18:00:00.000Z" } } ``` Sem `X-LGPD-Purpose` (ou com valor fora de `emissao_nfe`, `cadastro`, `cobranca`, `obrigacao_legal`, `contrato`, `credito`), o mesmo `422` sai com `code` `LGPD_PURPOSE_REQUIRED` e `detail` citando a lista de valores aceitos. Toda consulta de CPF (aceita ou recusada) é registrada em log de auditoria (Art. 37 LGPD). `POST /v1/companies` com um CNPJ que já existe como `Issuer` (o campo é único globalmente na base, não por parceiro) sempre volta `409` com o **mesmo** `code` e a **mesma** mensagem, não importa se o CNPJ já é seu ou de outro parceiro: ```json theme={null} { "error": { "type": "https://engineapi.com.br/errors/CNPJ_CONFLICT", "title": "Conflito", "status": 409, "detail": "CNPJ já cadastrado na plataforma como emissor. Se é seu, consulte GET /v1/companies; se não constar na sua lista, solicite a transferência em POST /v1/companies/transfer-request (cnpj e reason).", "instance": "/v1/companies", "requestId": "req_abc123", "timestamp": "2026-08-02T18:00:00.000Z" } } ``` **Mudança de contrato:** até 2026-07-31 este `409` trazia dois `code`s distintos: `CNPJ_CONFLICT_SAME_PARTNER` (é seu) e `CNPJ_CONFLICT_OTHER_PARTNER` (é de outro parceiro). Isso anulava o anti-oráculo da mensagem única: o `code` diferenciado (visível em `error.type`) permitia enumerar quais CNPJs de terceiros já têm emissor cadastrado na plataforma. Os dois codes foram colapsados em `CNPJ_CONFLICT`; quem ramificava por `code` precisa atualizar para tratar um único valor. Se o CNPJ é seu, o emissor já existe na sua conta, veja em `GET /v1/companies`. Se é de outro parceiro, use `POST /v1/companies/transfer-request` para solicitar a transferência (fila revisada manualmente pelo superadmin, com consentimento do dono atual). Ver [Transferência de emissor](/guides/transferencia-de-emissor). Assinatura em `PAST_DUE`: requisições `GET` continuam funcionando (modo leitura), qualquer outro método volta `402`: ```json theme={null} { "error": { "type": "https://engineapi.com.br/errors/PAYMENT_REQUIRED", "title": "Erro HTTP 402", "status": 402, "detail": "Sua assinatura está com pagamento pendente. Regularize para continuar utilizando a plataforma.", "instance": "/v1/nfe", "requestId": "req_abc123", "timestamp": "2026-07-20T18:00:00.000Z" } } ``` Assinatura `CANCELED` (ou sem nenhuma assinatura) responde `403` (Forbidden), não `402`. A distinção: `402` tem saída óbvia (pague e volte a emitir), `403` exige contratar/reativar um plano. `GET /v1/queries/cnpj/:cnpj` consulta um provedor externo (Receita Federal) que tem seu próprio rate limit, independente do seu plano na engineAPI: ```json theme={null} { "error": { "type": "https://engineapi.com.br/errors/TOO_MANY_REQUESTS", "title": "Limite de Requisições Excedido", "status": 429, "detail": "Rate limit da ReceitaWS atingido. Tente novamente em 1 minuto.", "instance": "/v1/queries/cnpj/11222333000181", "requestId": "req_abc123", "timestamp": "2026-07-20T18:00:00.000Z" } } ``` Distinto do `429`/`RATE_LIMIT_EXCEEDED` da [tabela de planos](#rate-limits) abaixo: ali é o teto do SEU plano na engineAPI; aqui é o teto do provedor de dados externo. *** ## Estratégia de Retry | Tipo de erro | Retry? | Quando | | ---------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------- | | `400` (validação ou rejeição SEFAZ) | Não | Corrija os dados primeiro. Reenvio com a mesma `Idempotency-Key` devolve a **mesma** rejeição, sem retransmitir à SEFAZ | | `401` Unauthorized | Não | Faça login e obtenha novo token | | `403` Forbidden | Não | Verifique permissões do plano ou o ambiente da API Key | | `404` Not Found | Não | Recurso não existe | | `422` Pré-voo (assistida/certificado/cadastro) | Não | Corrija o cadastro do emissor (IE, endereço, certificado) ou complete o campo manualmente | | `429` Rate Limit | Sim | Aguarde o tempo do header `Retry-After` | | `500` Server Error | Sim | Retry com backoff exponencial | | `503` SEFAZ/SEFIN indisponível | Sim | Retry após alguns minutos | ### Implementando Retry com Backoff Exponencial ```typescript theme={null} async function emitirComRetry(data: any, maxRetries = 3) { for (let attempt = 0; attempt < maxRetries; attempt++) { try { const resp = await fetch('https://api.engineapi.com.br/v1/nfe', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json', 'Idempotency-Key': `pedido-${data.pedidoId}-nfe`, }, body: JSON.stringify(data), }); if (resp.ok) return await resp.json(); const body = await resp.json(); // Não fazer retry em erros de dados/rejeição/permissão if ([400, 401, 403, 404, 422].includes(resp.status)) { throw new Error(`Erro não recuperável: ${body.error?.detail}`); } // Retry em 429/500/503 if (attempt < maxRetries - 1) { const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s await new Promise(resolve => setTimeout(resolve, delay)); continue; } } catch (err) { if (attempt === maxRetries - 1) throw err; } } } ``` ***

Rate Limits

Limites por plano, headers e o `429` (RFC 7807) estão em [Rate Limits](/guides/rate-limits), fonte única, não duplicada aqui. *** ## Veja também * **[Conceitos: CFOP e NCM](/conceitos/cfop-ncm-cst):** tabela de referência dos códigos fiscais mais usados. * **[Status SEFAZ](/conceitos/sefaz):** monitorar disponibilidade dos servidores SEFAZ.