Erros e Rejeições

Toda resposta de erro da engineAPI segue o padrão RFC 7807 (Problem Details), aplicado globalmente pelo HttpExceptionFilter. 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"
  }
}

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:

1. Se a exceção carrega um code (ou error) explícito, entre eles os códigos de negócio deste catálogo (CERTIFICADO_AUSENTE, CNPJ_CONFLICT etc.), o slug é esse valor, normalizado (maiúsculas, espaços viram _).
2. Sem code/error explícito, o slug cai num mapa fixo por status HTTP (400 vira BAD_REQUEST, 422 vira UNPROCESSABLE_ENTITY, 429 vira RATE_LIMIT_EXCEEDED etc.).
3. Payload de validação em formato de array (rejeição da validação de schema, global a toda a API) sempre vira VALIDATION_ERROR, independente do status.

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:

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:

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

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\": A NF-e referenciada (devolução, complementar e ajuste) ainda não é suportada pela engineAPI. Enviar o campo não geraria o grupo no documento e a SEFAZ rejeitaria a nota com cStat 321 depois de consumir o número fiscal. 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": "A NF-e referenciada (devolução, complementar e ajuste) ainda não é suportada pela engineAPI. Enviar o campo não geraria o grupo no documento e a SEFAZ rejeitaria a nota com cStat 321 depois de consumir o número fiscal."
        }
      ]
    },
    "instance": "/v1/nfe",
    "requestId": "req_uofirusmuamw",
    "timestamp": "2026-08-04T12:00:00.000Z"
  }
}

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:

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:

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:

No lote (POST /v1/nfe/batch) a recusa é tudo ou nada: uma chave desconhecida em uma única nota recusa o envio inteiro com 400, e nenhuma nota é enfileirada. Antes o lote respondia 201 e descartava a chave. O caminho é o mesmo do singular: caminho em camposDesconhecidos diz a nota pelo índice (ex.: notas[2].items[0].comb).

Checklist de migração:

1. Rode seus payloads de homologação uma vez. Campo a mais aparece em details.camposDesconhecidos com o caminho exato.
2. Remova os campos sem motivo (nome errado ou campo inexistente).
3. Para os campos com motivo, o grupo ainda não é suportado: retire do payload e trate o cenário fora da API até o suporte existir.

Códigos HTTP

Catálogo de códigos de negócio

Todo código abaixo é o code (ou error) que vira o slug de error.type (ver Como o slug nasce). É o catálogo completo dos codes de negócio hoje na API, fora dos slugs genéricos por status (BAD_REQUEST, UNAUTHORIZED, VALIDATION_ERROR etc., já cobertos acima).

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

Independente do módulo (NFe, NFCe, NFSe), a rejeição fiscal chega como 400 com error.erros[]. Alguns códigos comuns:

Emissão assistida (422): quando aparece

Só ocorre com resolverTributacao: true no payload de NFe/NFCe/NFSe. 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 NFe/NFCe, o corpo real inclui {index, motivo} por item não-resolvido; na NFSe, 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: Reforma Tributária: 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: Reforma Tributária: erros de IBS/CBS.

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

Antes de acionar o worker ACBr, a engineAPI valida se o cadastro do emissor (NFe e NFCe, o mesmo cadastro) tem o que o documento fiscal exige. Duas checagens, mesmo contrato de resposta:

Outros códigos de negócio

Estratégia de Retry

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

Não existe limite por minuto, hora ou dia: a janela é sempre de 1 segundo. Quando o limite é excedido, o erro também segue o envelope RFC 7807 (status: 429), com o header Retry-After (sempre 1, em segundos) indicando quando tentar novamente.

Próximos passos