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
- Formato do pedido
- Emissora, certificado e CSC
- Emissão
- Documentos e eventos
- Substituição
- Webhooks e e-mail
- Consultas à SEFAZ e ao Sistema Nacional
- Rejeições da SEFAZ
Autenticação e limites
| Código | Status | Quando | O que fazer |
|---|---|---|---|
NAO_AUTENTICADO | 401 | A 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_SUSPENSA | 403 | A conta dona da chave foi suspensa pelo operador. | Fale com o operador do motor. |
AMBIENTE_NAO_PERMITIDO | 403 | Uma chave de teste tentou operar em produção. | Use a chave de produção da conta, ou mande "ambiente": "simulado" ou "homologacao". |
LIMITE_DE_REQUISICOES | 429 | A 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ódigo | Status | Quando | O que fazer |
|---|---|---|---|
VALIDACAO | 422 | Um 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_INVALIDO | 400 | O 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_INVALIDO | 415 | O 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_DEMAIS | 413 | O 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_INVALIDO | 422 | A 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_INVALIDO | 422 | O 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_INVALIDA | 400 | A Idempotency-Key passou de 200 caracteres. | Use uma chave mais curta, como o id do pedido no seu sistema. |
IDEMPOTENCIA_CONFLITANTE | 422 | A 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_INEXISTENTE | 404 | O caminho não existe na API. | Confira o caminho e o método na referência. |
NAO_ENCONTRADO | 404 | O identificador do caminho não é um UUID. | Use o id devolvido pela API. |
EXEMPLO_INEXISTENTE | 404 | O 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_INTERNO | 500 | Falha inesperada no motor. | Tente de novo. Se continuar, informe ao suporte o valor do cabeçalho X-Request-Id. |
Emissora, certificado e CSC
| Código | Status | Quando | O que fazer |
|---|---|---|---|
EMISSORA_NAO_ENCONTRADA | 404 | A emissora não existe nesta conta. | Use o id devolvido por POST /v1/emissoras ou listado em GET /v1/emissoras. |
EMISSORA_JA_CADASTRADA | 409 | O CNPJ já é uma emissora da conta. | Use a emissora existente (GET /v1/emissoras) ou altere-a com PATCH. |
CERTIFICADO_AUSENTE | 422 | A 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_ILEGIVEL | 422 | O arquivo não é um PFX, ou a senha está errada. | Confira o arquivo (A1, .pfx ou .p12) e a senha. |
CERTIFICADO_VENCIDO | 422 | O certificado está fora da validade. | Renove o certificado A1 com a autoridade certificadora e envie o novo. |
CERTIFICADO_DE_OUTRO_CNPJ | 422 | O CNPJ do certificado não é o da emissora. | Envie o certificado A1 emitido para o CNPJ desta emissora. |
CERTIFICADO_GRANDE_DEMAIS | 413 | O arquivo passa de 64 KB. | Confira se é mesmo o .pfx do certificado A1. |
CSC_AUSENTE | 422 | A 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_AUSENTE | 404 | A emissora não tem logo. | Envie a logo em PUT /v1/emissoras/{id}/logo, se quiser vê-la na DANFE. |
LOGO_INVALIDA | 422 | O arquivo não é PNG nem JPEG. | Converta a imagem para PNG ou JPEG. |
LOGO_GRANDE_DEMAIS | 413 | A logo passa de 512 KB. | Reduza a imagem; na DANFE ela ocupa uns três centímetros. |
NUMERO_JA_USADO | 422 | O 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ódigo | Status | Quando | O que fazer |
|---|---|---|---|
AMBIENTE_INDISPONIVEL | 422 | A 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_ATENDIDA | 422 | O 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_CBS | 422 | A 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_CUPOM | 422 | O pedido de NF-e trouxe o campo contingencia. | Retire o campo; a contingência offline é só da NFC-e. |
NUMERO_EM_USO | 409 | O numero informado já tem nota nesta série. | Deixe o motor numerar (omita numero) ou use um número livre. |
NUMERO_INUTILIZADO | 409 | O numero informado foi inutilizado nesta série. | Use outro número; um número inutilizado não volta a valer. |
Documentos e eventos
| Código | Status | Quando | O que fazer |
|---|---|---|---|
DOCUMENTO_NAO_ENCONTRADO | 404 | O documento não existe nesta conta. | Use o id devolvido na emissão. |
XML_INDISPONIVEL | 409 | O 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_INDISPONIVEL | 409 | A 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_PERMITE | 409 | Cancelamento ou carta de correção de nota que não está autorizada. | Consulte o documento; só nota autorizada recebe eventos. |
EVENTO_EM_ANDAMENTO | 409 | Já há um evento desta nota em transmissão. | Espere o evento atual terminar (GET /v1/documentos/{id}/eventos) e tente de novo. |
EVENTO_NAO_EXISTE | 422 | O 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_CANCELAMENTO | 422 | O prazo para cancelar o cupom já passou. | Emita uma nota de devolução ou de ajuste no lugar do cancelamento. |
LIMITE_DE_CORRECOES | 422 | A 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_ENCONTRADA | 404 | A inutilização não existe nesta conta. | Use o id devolvido por POST /v1/inutilizacoes. |
FAIXA_JA_INUTILIZADA | 409 | Parte 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_USO | 422 | A faixa a inutilizar tem notas emitidas. | Inutilize só números que nunca viraram nota; nota emitida se cancela. |
Substituição
| Código | Status | Quando | O que fazer |
|---|---|---|---|
SUBSTITUICAO_SO_NO_CUPOM | 422 | O 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_ENCONTRADO | 422 | O cupom indicado em substitui não existe nesta conta. | Use o id do cupom enviado que ficou sem resposta. |
SUBSTITUIDO_INVALIDO | 422 | O cupom a substituir é de outra emissora ou de outro ambiente. | O substituto precisa ser da mesma emissora e do mesmo ambiente. |
JA_SUBSTITUIDO | 409 | O cupom indicado já tem um substituto. | Consulte o cupom; a substituição já está em curso ou concluída. |
PRIMEIRO_JA_DECIDIDO | 409 | O cupom que se queria substituir já teve desfecho (autorizado, rejeitado). | Use o primeiro cupom; não há o que substituir. |
SUBSTITUTO_NAO_ENCONTRADO | 404 | No cancelamento por substituição, o cupom substituto não existe nesta conta. | Confira o id do cupom de contingência. |
SUBSTITUTO_INVALIDO | 422 | O 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_AUTORIZADO | 409 | O cupom substituto ainda não foi autorizado. | Espere a autorização do cupom de contingência e tente de novo. |
SUBSTITUIDA_NAO_ENCONTRADA | 422 | A NFS-e indicada em substitui não existe nesta conta. | Use o id da NFS-e autorizada que será substituída. |
SUBSTITUIDA_INVALIDA | 422 | A 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_AUTORIZADA | 409 | Só NFS-e autorizada pode ser substituída. | Consulte a situação da NFS-e original. |
JA_SUBSTITUIDA | 409 | A NFS-e já tem uma substituta. | Consulte a substituta; uma NFS-e só é substituída uma vez. |
Webhooks e e-mail
| Código | Status | Quando | O que fazer |
|---|---|---|---|
URL_INVALIDA | 422 | A URL do webhook não é https pública (endereço local ou privado é recusado). | Use uma URL https acessível pela internet. |
EVENTO_DESCONHECIDO | 422 | A lista eventos tem um nome que não existe. | Use os eventos da referência (documento.autorizado, documento.rejeitado e os demais). |
LIMITE_DE_WEBHOOKS | 422 | A conta já tem 10 webhooks. | Remova um webhook antes de criar outro. |
WEBHOOK_NAO_ENCONTRADO | 404 | O webhook não existe nesta conta. | Liste os webhooks em GET /v1/webhooks. |
EMAIL_INDISPONIVEL | 503 | Este 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ódigo | Status | Quando | O que fazer |
|---|---|---|---|
SEFAZ_INDISPONIVEL | 502 | A SEFAZ (ou o Ambiente Nacional) não respondeu. | Tente de novo em alguns minutos. |
SISTEMA_NACIONAL_INDISPONIVEL | 502 | O Sistema Nacional da NFS-e não respondeu. | Tente de novo em alguns minutos. |
CONSULTA_INDISPONIVEL | 503 | O motor não tem o certificado de consulta configurado. | Fale com o operador do motor. |
CONSULTA_ANTECIPADA | 429 | A 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_CERTIFICADO | 422 | A distribuição de documentos pede o certificado da própria emissora, e ela não tem. | Envie o certificado da emissora. |
CNPJ_NAO_ENCONTRADO | 404 | O 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_INDISPONIVEL | 502 | A 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_ATENDIDO | 422 | A SEFAZ da UF não oferece a consulta cadastro. | Consulte o contribuinte no portal da SEFAZ da UF. |
CADASTRO_RECUSADO_PELA_SEFAZ | 503 | A 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.
| cStat | O que significa | O que fazer |
|---|---|---|
| 135 | Evento registrado e vinculado à nota. | |
| 136 | Evento registrado, mas ainda não vinculado à nota. | Consulte a nota em alguns minutos. |
| 155 | Cancelamento aceito fora do prazo normal. | |
| 156 | Emitente sem inscrição estadual não pode emitir NFC-e. | Use NF-e, ou cadastre a inscrição estadual da empresa. |
| 157 | Emitente sem inscrição estadual precisa informar o CNPJ. | |
| 158 | Emitente sem inscrição estadual não informa IE de substituto tributário. | |
| 159 | O 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). |
| 161 | Emitente sem inscrição estadual não informa ICMS. | Retire o grupo ICMS dos itens. |
| 162 | Emitente sem inscrição estadual precisa do grupo IBS/CBS em cada item. | Informe o grupo IBSCBS dos itens. |
| 163 | A empresa tem inscrição estadual ativa na UF, mas a nota saiu sem ela. | Cadastre a inscrição estadual na emissora. |
| 164 | O emitente está com situação irregular na UF. | Regularize o cadastro com a SEFAZ. |
| 166 | Emitente sem inscrição estadual só é autorizado pela SVRS. | Confira a inscrição estadual da emissora; sem ela, o motor envia à SVRS. |
| 178 | O CNPJ do emitente não está no cadastro da Receita Federal. | |
| 179 | O CNPJ do emitente está com situação irregular na Receita Federal. | |
| 180 | O regime tributário (CRT) diverge do cadastro na Receita Federal. | Confira o CRT da emissora (1 Simples, 3 regime normal, 4 MEI). |
| 181 | O CNPJ do destinatário não está no cadastro da Receita Federal. | |
| 182 | O CNPJ do destinatário está com situação irregular na Receita Federal. | |
| 188 | Evento de nota de emitente sem inscrição estadual precisa ir à SVRS. | |
| 204 | Esta nota já foi enviada e está registrada na SEFAZ. | Consulte a nota pela chave de acesso. |
| 225 | O 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. |
| 301 | A SEFAZ negou o uso da nota por irregularidade fiscal do emitente. | Regularize a inscrição estadual da empresa com a SEFAZ antes de emitir. |
| 302 | A SEFAZ negou o uso da nota por irregularidade fiscal do destinatário. | Confira a situação cadastral do destinatário. |
| 501 | O prazo de cancelamento desta UF já passou. | Emita uma nota de devolução ou de ajuste no lugar do cancelamento. |
| 539 | Já 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. |
| 573 | Este evento já estava registrado na SEFAZ. |