Motor de Emissão

Erros

Toda recusa da API traz um codigo estável. Trate pelo código, não pela mensagem: o texto pode melhorar, o código não muda.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "urn:motor-emissao:erro:certificado_vencido",
  "title": "O certificado está fora da validade: venceu em 01/10/2026.",
  "status": 422,
  "codigo": "CERTIFICADO_VENCIDO",
  "acao": "Renove o certificado A1 com a autoridade certificadora.",
  "requisicao": "9f2c4e7a1b3d5f60"
}

title é a mensagem para mostrar ao usuário. Quando o erro é de um campo, vem campo; quando são vários, a lista erros traz um item por campo. requisicao é o mesmo valor do cabeçalho X-Request-Id.

Erro da API e rejeição da SEFAZ são coisas diferentes. Os códigos abaixo são recusas do próprio motor, na hora do pedido, e nada foi transmitido. Já a nota que a SEFAZ rejeita foi aceita pela API (202) e termina com status rejeitado: o motivo vem em codigo_sefaz e motivo_sefaz, e a explicação em rejeicao (veja rejeições da SEFAZ).

Índice

Autenticação e limites

CódigoStatusQuandoO que fazer
NAO_AUTENTICADO401A requisição veio sem o cabeçalho Authorization, ou com uma chave inválida ou revogada.Envie Authorization: Bearer <chave>. Se a chave foi revogada, peça outra ao operador do motor.
CONTA_SUSPENSA403A conta dona da chave foi suspensa pelo operador.Fale com o operador do motor.
AMBIENTE_NAO_PERMITIDO403Uma chave de teste tentou operar em produção.Use a chave de produção da conta, ou mande "ambiente": "simulado" ou "homologacao".
LIMITE_DE_REQUISICOES429A conta passou do limite de requisições por minuto (emissões e demais rotas têm limites separados).Espere os segundos do cabeçalho Retry-After e repita. Os limites da conta aparecem em GET /v1/conta.

Formato do pedido

CódigoStatusQuandoO que fazer
VALIDACAO422Um ou mais campos não passaram na conferência. A lista erros traz cada campo e o motivo.Corrija os campos apontados em erros (ou em campo) e envie de novo.
JSON_INVALIDO400O corpo não é um JSON válido, ou tem um tipo errado para a rota.Confira o JSON (vírgulas, aspas, números como texto onde o leiaute pede texto).
FORMATO_INVALIDO415O Content-Type não é o esperado pela rota (application/json, ou multipart/form-data no certificado e na logo).Envie o cabeçalho Content-Type certo; a mensagem diz qual.
CORPO_GRANDE_DEMAIS413O corpo passou do limite da rota (2 MB para notas, 256 KB para o resto).Divida a nota ou reduza o conteúdo; uma nota fiscal não chega perto desse limite.
LEIAUTE_INVALIDO422A nota tem campos que não existem no leiaute (NF-e 4.00 ou DPS nacional), ou grupos fora de lugar.Confira os nomes (diferenciam maiúsculas) e a posição dos grupos; a lista erros aponta cada um.
ESQUEMA_INVALIDO422O XML montado não passou na validação do esquema oficial (XSD), antes de ir para a SEFAZ.Corrija os campos apontados; as mensagens são as do validador do leiaute.
IDEMPOTENCIA_INVALIDA400A Idempotency-Key passou de 200 caracteres.Use uma chave mais curta, como o id do pedido no seu sistema.
IDEMPOTENCIA_CONFLITANTE422A mesma Idempotency-Key já foi usada com um corpo diferente.Use uma chave nova para um pedido novo. Para repetir o mesmo pedido, mande o mesmo corpo.
ROTA_INEXISTENTE404O caminho não existe na API.Confira o caminho e o método na referência.
NAO_ENCONTRADO404O identificador do caminho não é um UUID.Use o id devolvido pela API.
EXEMPLO_INEXISTENTE404O arquivo pedido em /docs/exemplos não existe.Use os nomes que aparecem nos guias (emissora.json, nfe.json, nfse.json e os demais).
ERRO_INTERNO500Falha inesperada no motor.Tente de novo. Se continuar, informe ao suporte o valor do cabeçalho X-Request-Id.

Emissora, certificado e CSC

CódigoStatusQuandoO que fazer
EMISSORA_NAO_ENCONTRADA404A emissora não existe nesta conta.Use o id devolvido por POST /v1/emissoras ou listado em GET /v1/emissoras.
EMISSORA_JA_CADASTRADA409O CNPJ já é uma emissora da conta.Use a emissora existente (GET /v1/emissoras) ou altere-a com PATCH.
CERTIFICADO_AUSENTE422A emissora não tem certificado A1 e a nota é de homologação ou produção. Em GET do certificado, sai com 404.Envie o .pfx em PUT /v1/emissoras/{id}/certificado. No ambiente simulado, o motor assina com um certificado de teste e não exige o da emissora.
CERTIFICADO_ILEGIVEL422O arquivo não é um PFX, ou a senha está errada.Confira o arquivo (A1, .pfx ou .p12) e a senha.
CERTIFICADO_VENCIDO422O certificado está fora da validade.Renove o certificado A1 com a autoridade certificadora e envie o novo.
CERTIFICADO_DE_OUTRO_CNPJ422O CNPJ do certificado não é o da emissora.Envie o certificado A1 emitido para o CNPJ desta emissora.
CERTIFICADO_GRANDE_DEMAIS413O arquivo passa de 64 KB.Confira se é mesmo o .pfx do certificado A1.
CSC_AUSENTE422A emissora não tem CSC (código de segurança do contribuinte) no ambiente da NFC-e.Envie o CSC em PUT /v1/emissoras/{id}/csc. No simulado, qualquer valor serve.
LOGO_AUSENTE404A emissora não tem logo.Envie a logo em PUT /v1/emissoras/{id}/logo, se quiser vê-la na DANFE.
LOGO_INVALIDA422O arquivo não é PNG nem JPEG.Converta a imagem para PNG ou JPEG.
LOGO_GRANDE_DEMAIS413A logo passa de 512 KB.Reduza a imagem; na DANFE ela ocupa uns três centímetros.
NUMERO_JA_USADO422O próximo número pedido para a série é menor ou igual a um número já emitido.Informe um número maior que o último emitido na série.

Emissão

CódigoStatusQuandoO que fazer
AMBIENTE_INDISPONIVEL422A emissão em produção ainda não foi liberada para esta emissora e este tipo de documento.Peça a liberação ao operador do motor. Enquanto isso, use homologacao ou simulado.
UF_NAO_ATENDIDA422O motor ainda não transmite para a autorizadora da UF da emissora.Use o ambiente simulado enquanto a UF não é atendida, e fale com o operador.
CONTRIBUINTE_EXCLUSIVO_IBS_CBS422A emissora não tem inscrição estadual e a nota trouxe ICMS ou não trouxe o IBS/CBS dos itens.Retire o ICMS e informe o grupo IBSCBS dos itens, ou cadastre a inscrição estadual da emissora.
CONTINGENCIA_SO_NO_CUPOM422O pedido de NF-e trouxe o campo contingencia.Retire o campo; a contingência offline é só da NFC-e.
NUMERO_EM_USO409O numero informado já tem nota nesta série.Deixe o motor numerar (omita numero) ou use um número livre.
NUMERO_INUTILIZADO409O numero informado foi inutilizado nesta série.Use outro número; um número inutilizado não volta a valer.

Documentos e eventos

CódigoStatusQuandoO que fazer
DOCUMENTO_NAO_ENCONTRADO404O documento não existe nesta conta.Use o id devolvido na emissão.
XML_INDISPONIVEL409O XML (ou o envio por e-mail) foi pedido antes de a nota ser autorizada.Espere o status autorizado (pelo webhook documento.autorizado ou consultando o documento).
DANFE_INDISPONIVEL409A nota ainda não tem XML guardado com os dados que a DANFE imprime.Espere a autorização e peça o PDF de novo.
SITUACAO_NAO_PERMITE409Cancelamento ou carta de correção de nota que não está autorizada.Consulte o documento; só nota autorizada recebe eventos.
EVENTO_EM_ANDAMENTO409Já há um evento desta nota em transmissão.Espere o evento atual terminar (GET /v1/documentos/{id}/eventos) e tente de novo.
EVENTO_NAO_EXISTE422O evento pedido não existe para este modelo (carta de correção de NFS-e, cancelamento por substituição fora da NFC-e).Confira na referência quais eventos cada modelo aceita.
PRAZO_DE_CANCELAMENTO422O prazo para cancelar o cupom já passou.Emita uma nota de devolução ou de ajuste no lugar do cancelamento.
LIMITE_DE_CORRECOES422A nota já tem 20 cartas de correção, o máximo da SEFAZ.A última carta vale por todas; se ainda há o que corrigir, avalie cancelar e emitir de novo.
INUTILIZACAO_NAO_ENCONTRADA404A inutilização não existe nesta conta.Use o id devolvido por POST /v1/inutilizacoes.
FAIXA_JA_INUTILIZADA409Parte da faixa já foi inutilizada ou está em inutilização.Consulte as lacunas da série (GET /v1/emissoras/{id}/lacunas) e peça só a parte livre.
NUMEROS_EM_USO422A faixa a inutilizar tem notas emitidas.Inutilize só números que nunca viraram nota; nota emitida se cancela.

Substituição

CódigoStatusQuandoO que fazer
SUBSTITUICAO_SO_NO_CUPOM422O campo substitui foi enviado numa NF-e.Retire o campo; o cupom substituto é só da NFC-e (na NFS-e, use o substitui da DPS).
SUBSTITUIDO_NAO_ENCONTRADO422O cupom indicado em substitui não existe nesta conta.Use o id do cupom enviado que ficou sem resposta.
SUBSTITUIDO_INVALIDO422O cupom a substituir é de outra emissora ou de outro ambiente.O substituto precisa ser da mesma emissora e do mesmo ambiente.
JA_SUBSTITUIDO409O cupom indicado já tem um substituto.Consulte o cupom; a substituição já está em curso ou concluída.
PRIMEIRO_JA_DECIDIDO409O cupom que se queria substituir já teve desfecho (autorizado, rejeitado).Use o primeiro cupom; não há o que substituir.
SUBSTITUTO_NAO_ENCONTRADO404No cancelamento por substituição, o cupom substituto não existe nesta conta.Confira o id do cupom de contingência.
SUBSTITUTO_INVALIDO422O substituto é de outra emissora, de outro ambiente ou não é cupom.Indique o cupom de contingência da mesma emissora e do mesmo ambiente.
SUBSTITUTO_NAO_AUTORIZADO409O cupom substituto ainda não foi autorizado.Espere a autorização do cupom de contingência e tente de novo.
SUBSTITUIDA_NAO_ENCONTRADA422A NFS-e indicada em substitui não existe nesta conta.Use o id da NFS-e autorizada que será substituída.
SUBSTITUIDA_INVALIDA422A nota a substituir não é NFS-e, ou é de outra emissora ou de outro ambiente.Indique uma NFS-e da mesma emissora e do mesmo ambiente.
SUBSTITUIDA_NAO_AUTORIZADA409Só NFS-e autorizada pode ser substituída.Consulte a situação da NFS-e original.
JA_SUBSTITUIDA409A NFS-e já tem uma substituta.Consulte a substituta; uma NFS-e só é substituída uma vez.

Webhooks e e-mail

CódigoStatusQuandoO que fazer
URL_INVALIDA422A URL do webhook não é https pública (endereço local ou privado é recusado).Use uma URL https acessível pela internet.
EVENTO_DESCONHECIDO422A lista eventos tem um nome que não existe.Use os eventos da referência (documento.autorizado, documento.rejeitado e os demais).
LIMITE_DE_WEBHOOKS422A conta já tem 10 webhooks.Remova um webhook antes de criar outro.
WEBHOOK_NAO_ENCONTRADO404O webhook não existe nesta conta.Liste os webhooks em GET /v1/webhooks.
EMAIL_INDISPONIVEL503Este motor ainda não tem servidor de e-mail configurado.Envie o XML e o PDF pelo seu sistema enquanto isso.

Consultas à SEFAZ e ao Sistema Nacional

CódigoStatusQuandoO que fazer
SEFAZ_INDISPONIVEL502A SEFAZ (ou o Ambiente Nacional) não respondeu.Tente de novo em alguns minutos.
SISTEMA_NACIONAL_INDISPONIVEL502O Sistema Nacional da NFS-e não respondeu.Tente de novo em alguns minutos.
CONSULTA_INDISPONIVEL503O motor não tem o certificado de consulta configurado.Fale com o operador do motor.
CONSULTA_ANTECIPADA429A SEFAZ só aceita nova consulta de distribuição desta empresa mais tarde; antes disso bloqueia o CNPJ por uma hora.Espere o horário da mensagem.
SEM_CERTIFICADO422A distribuição de documentos pede o certificado da própria emissora, e ela não tem.Envie o certificado da emissora.
CNPJ_NAO_ENCONTRADO404O CNPJ não está nos dados abertos da Receita Federal.Confira o número. CNPJ aberto há poucas semanas pode ainda não constar: a base é atualizada uma vez por mês.
RECEITA_INDISPONIVEL502A consulta à Receita Federal (BrasilAPI) não respondeu, passou de 10 segundos ou pediu para esperar.Tente de novo em alguns minutos, ou preencha os dados à mão.
CADASTRO_NAO_ATENDIDO422A SEFAZ da UF não oferece a consulta cadastro.Consulte o contribuinte no portal da SEFAZ da UF.
CADASTRO_RECUSADO_PELA_SEFAZ503A SEFAZ recusou a consulta cadastro (por exemplo, o serviço está bloqueado para o certificado do motor).Tente mais tarde; se persistir, fale com o operador do motor.

Rejeições da SEFAZ

Os códigos da SEFAZ (cStat) são muitos e mudam com as notas técnicas. Estes o motor já explica no campo rejeicao da nota; para os demais, o motivo_sefaz traz o texto oficial.

cStatO que significaO que fazer
135Evento registrado e vinculado à nota.
136Evento registrado, mas ainda não vinculado à nota.Consulte a nota em alguns minutos.
155Cancelamento aceito fora do prazo normal.
156Emitente sem inscrição estadual não pode emitir NFC-e.Use NF-e, ou cadastre a inscrição estadual da empresa.
157Emitente sem inscrição estadual precisa informar o CNPJ.
158Emitente sem inscrição estadual não informa IE de substituto tributário.
159O CFOP do item não é permitido para emitente sem inscrição estadual.Use um CFOP da tabela de contribuinte exclusivo do IBS/CBS (coluna indExcIBSCBS).
161Emitente sem inscrição estadual não informa ICMS.Retire o grupo ICMS dos itens.
162Emitente sem inscrição estadual precisa do grupo IBS/CBS em cada item.Informe o grupo IBSCBS dos itens.
163A empresa tem inscrição estadual ativa na UF, mas a nota saiu sem ela.Cadastre a inscrição estadual na emissora.
164O emitente está com situação irregular na UF.Regularize o cadastro com a SEFAZ.
166Emitente sem inscrição estadual só é autorizado pela SVRS.Confira a inscrição estadual da emissora; sem ela, o motor envia à SVRS.
178O CNPJ do emitente não está no cadastro da Receita Federal.
179O CNPJ do emitente está com situação irregular na Receita Federal.
180O regime tributário (CRT) diverge do cadastro na Receita Federal.Confira o CRT da emissora (1 Simples, 3 regime normal, 4 MEI).
181O CNPJ do destinatário não está no cadastro da Receita Federal.
182O CNPJ do destinatário está com situação irregular na Receita Federal.
188Evento de nota de emitente sem inscrição estadual precisa ir à SVRS.
204Esta nota já foi enviada e está registrada na SEFAZ.Consulte a nota pela chave de acesso.
225O XML da nota não passou na validação de esquema da SEFAZ.Confira os campos obrigatórios e os formatos do leiaute 4.00.
301A SEFAZ negou o uso da nota por irregularidade fiscal do emitente.Regularize a inscrição estadual da empresa com a SEFAZ antes de emitir.
302A SEFAZ negou o uso da nota por irregularidade fiscal do destinatário.Confira a situação cadastral do destinatário.
501O prazo de cancelamento desta UF já passou.Emita uma nota de devolução ou de ajuste no lugar do cancelamento.
539Já existe nota com este número e outra chave de acesso.Consulte a nota existente ou use o próximo número da série.
573Este evento já estava registrado na SEFAZ.