Erros e respostas

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)

{
  "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/<CODIGO>`)
`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
`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 <SLUG> em .../errors/<SLUG>) é resolvido nesta ordem, pelo filtro global de exceções:

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 _).
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.).
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

// 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.

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

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

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 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:

Rode seus payloads de homologação uma vez. Campo a mais aparece em details.camposDesconhecidos com o caminho exato.
Remova os campos sem motivo (nome errado ou campo inexistente).
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:

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

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

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):

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

{
  "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):

{
  "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):

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

{
  "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 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 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). 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 codes 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) e fora da rejeição SEFAZ/SEFIN (erros[], passthrough do Fisco — ver Rejeição SEFAZ/SEFIN). 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 , 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 .	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, Emissão assistida, finNFe sem documento referenciado, Documento referenciado inválido e Outros códigos de negócio.

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.

Códigos genéricos e operacionais

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:

Erros de Identificação do Documento

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
`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

Erros de Certificado Digital

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

Erros de Valores e Cálculos

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)

Erros de Ambiente

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
`999`	Rejeição: erro não catalogado	Erro interno SEFAZ	Tente novamente; se persistir, contate suporte

Erros de Endereço

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

Erros de Cancelamento

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

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:

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

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 codes 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.

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:

CERTIFICADO_AUSENTE: certificado A1 não instalado

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

CADASTRO_EMISSOR_INCOMPLETO: IE ou endereço faltando

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:

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

CSC_AUSENTE: CSC/cscId não configurados (só NFC-e)

Exclusivo da NFC-e (modelo 65): fora do ambiente sandbox, csc (o token) e cscId (o ID do token) precisam estar cadastrados no emissor:

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

NUMERO_JA_UTILIZADO: número fiscal já usado por outro documento

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.

PAGAMENTO_SEM_DADOS_DO_MEIO: cartão/PIX sem os dados do meio

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.

PAGAMENTO_DIVERGENTE: pagamentos não fecham com o total

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.

DESCONTO_INVALIDO: desconto que o documento não consegue representar

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_INVALIDA: coerência da fatura e das duplicatas (422)

cobranca.fatura e cobranca.duplicatas[] (venda a prazo, Guia: 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.

FRETE_SEGURO_OUTRO_INVALIDO: valores inválidos de frete/seguro/outras despesas ou indTot

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).

VNF_INVALIDO: o total da nota ficaria negativo, ou nenhum item compõe o total

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.

PIS/COFINS/IPI/CEST/ICMS-ST: recusa em vez de campo ignorado (422)

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).

CST/CSOSN × regime do emissor (422 antes da SEFAZ)

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). 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.

GET /v1/queries/cpf/:cpf exige dois headers de compliance LGPD antes de consultar a Receita Federal (via SerPro). Sem X-LGPD-Consent: true:

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

CNPJ_CONFLICT: cadastro de empresa

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:

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

PAYMENT_REQUIRED: assinatura com pagamento pendente

Assinatura em PAST_DUE: requisições GET continuam funcionando (modo leitura), qualquer outro método volta 402:

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

TOO_MANY_REQUESTS: rate limit do provedor externo de CNPJ

GET /v1/queries/cnpj/:cnpj consulta um provedor externo (Receita Federal) que tem seu próprio rate limit, independente do seu plano na engineAPI:

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

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, fonte única, não duplicada aqui.

Veja também

Conceitos: CFOP e NCM: tabela de referência dos códigos fiscais mais usados.
Status SEFAZ: monitorar disponibilidade dos servidores SEFAZ.

Comece aqui

Emissão

Tributação

Erros e operação

IA e automação

Conceitos

Migração

Perguntas frequentes

Formato de Erro (RFC 7807)

Timeout depois de emitir: consulte, não reemita

Como o slug de `error.type` nasce

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

`null`, `""` e campo ausente no `PATCH`

Casas decimais em valores monetários (400)

Campo desconhecido no payload (400)

Campos do leiaute que existem no contrato com outro nome

Recursos fiscais suportados por passthrough

Campos do leiaute que a engineAPI ainda não suporta

O que muda para quem já integra

Quando a SEFAZ rejeita: como ver o que foi transmitido

`finNFe` 2, 3 ou 4 sem o documento referenciado (422)

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

Códigos HTTP

Catálogo de códigos de negócio

Códigos genéricos e operacionais

Rejeição SEFAZ/SEFIN (400): exemplos

Emissão assistida (422): quando aparece

Espelho fiscal divergente

NCM multiclasse

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

Outros códigos de negócio

Domínio efetivo de CSOSN, por (crt, modelo)

Estratégia de Retry

Implementando Retry com Backoff Exponencial

Rate Limits

Veja também

​Formato de Erro (RFC 7807)

​Timeout depois de emitir: consulte, não reemita

​Como o slug de error.type nasce

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

​null, "" e campo ausente no PATCH

​Casas decimais em valores monetários (400)

​Campo desconhecido no payload (400)

​Campos do leiaute que existem no contrato com outro nome

​Recursos fiscais suportados por passthrough

​Campos do leiaute que a engineAPI ainda não suporta

​O que muda para quem já integra

​Quando a SEFAZ rejeita: como ver o que foi transmitido

​finNFe 2, 3 ou 4 sem o documento referenciado (422)

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

​Códigos HTTP

​Catálogo de códigos de negócio

​Códigos genéricos e operacionais

​Rejeição SEFAZ/SEFIN (400): exemplos

​Emissão assistida (422): quando aparece

​Espelho fiscal divergente

​NCM multiclasse

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

​Outros códigos de negócio

​Domínio efetivo de CSOSN, por (crt, modelo)

​Estratégia de Retry

​Implementando Retry com Backoff Exponencial

​Rate Limits

​Veja também

Formato de Erro (RFC 7807)

Timeout depois de emitir: consulte, não reemita

Como o slug de `error.type` nasce

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

`null`, `""` e campo ausente no `PATCH`

Casas decimais em valores monetários (400)

Campo desconhecido no payload (400)

Campos do leiaute que existem no contrato com outro nome

Recursos fiscais suportados por passthrough

Campos do leiaute que a engineAPI ainda não suporta

O que muda para quem já integra

Quando a SEFAZ rejeita: como ver o que foi transmitido

`finNFe` 2, 3 ou 4 sem o documento referenciado (422)

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

Códigos HTTP

Catálogo de códigos de negócio

Códigos genéricos e operacionais

Rejeição SEFAZ/SEFIN (400): exemplos

Emissão assistida (422): quando aparece

Espelho fiscal divergente

NCM multiclasse

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

Outros códigos de negócio

Domínio efetivo de CSOSN, por (crt, modelo)

Estratégia de Retry

Implementando Retry com Backoff Exponencial

Rate Limits

Veja também