Referência
Códigos de erro
Referência consolidada de códigos de erro da Open API da TF Fiscal, agrupada por camada e domínio, com status HTTP, cenário e tratamento recomendado.
Formatos de erro
Os erros têm três formatos conforme a camada que os produziu, veja Convenções gerais:
| Camada | HTTP | Formato | Campo do código |
|---|---|---|---|
| Gateway da plataforma (autenticação, assinatura de APIs, limite de taxa, tamanho do corpo, links de download) | 401 / 403 / 404 / 413 / 429 / 503 | Envelope da plataforma {success, errorType, code, message} | code (inteiro) |
| Empresas, NF-e, NFC-e, CT-e, DC-e, NFS-e, e-mail de notas, registro de webhook | 400 / 404 / 409 / 500 | Array [{codigo, mensagem}], uma entrada por problema | codigo (string) |
| Verificação de NF-e e consulta cadastral | 400 / 404 / 409 / 422 / 428 / 451 / 500 / 503 | Objeto simples {code, message} | code (inteiro) |
| Endpoints da NFC-e offline | 200 / 400 / 404 | Envelope da plataforma; erros de negócio também em HTTP 200 | code (inteiro) |
| Interface local do Assistente Fiscal | 400 / 404 / 409 / 429 / 500 / 503; autenticação 401 / 403 | Erros de negócio em array [{codigo, mensagem}]; erros de autenticação no envelope da plataforma | codigo / code |
| SDK embarcado | nenhum | Codigo e Tipo da exceção | Codigo (inteiro) |
As mensagens são localizadas pelos cabeçalhos Language / Accept-Language (padrão português). Ramifique pelos códigos, nunca pelo texto da mensagem. No formato array todo codigo é o código de erro da plataforma como string numérica.
Faixas de código por domínio:
| Faixa | Domínio |
|---|---|
| 10001xxx | Validação de requisição e falhas da plataforma |
| 10003xxx | Empresa e certificado |
| 10004xxx | Emissão, cancelamento e carta de correção de NF-e |
| 10005xxx | Motor tributário |
| 10009xxx | Plataforma aberta (autenticação, assinatura, limite de taxa, webhooks, links de download) |
| 10013xxx | Download de arquivos |
| 10015xxx | Verificação de NF-e |
| 10016xxx | Consulta cadastral (CNPJ / CPF) |
| 10017xxx | CT-e |
| 10018xxx | NFS-e |
| 10019xxx | DC-e |
| 10021xxx | E-mail de notas |
| 10022xxx | NFC-e |
| 10029xxx | NFC-e offline (endpoints abertos, pareamento de dispositivos, núcleo de emissão offline, SDK, Assistente Fiscal) |
Gateway: autenticação e autorização
Formato de envelope da plataforma, produzido antes de a requisição chegar à API. 401 e 403 são erros de configuração; repetir sem corrigir é inútil e pode acionar o limite de taxa. Veja Autenticação para o esquema de assinatura.
| HTTP | code | Significado | Ação |
|---|---|---|---|
| 401 | 10009000 | Cabeçalhos de assinatura ausentes (token / sign / timestamp) | Envie os três cabeçalhos em toda requisição |
| 401 | 10009001 | Timestamp inválido ou desvio de relógio acima de ±300 s | Sincronize o relógio (NTP); gere o timestamp a cada requisição, nunca reutilize |
| 401 | 10009002 | Token inválido | Verifique o app_secret; se foi rotacionado, atualize a configuração |
| 401 | 10009003 | Assinatura divergente | Recalcule a assinatura; veja a lista de verificação em Autenticação |
| 403 | 10009004 | Aplicação desativada | Contate a plataforma |
| 403 | 10009015 | Aplicação não efetiva (aguardando aprovação ou rejeitada) | Aguarde a aprovação / contate a plataforma |
| 403 | 10009014 | Conta do integrador desativada | Contate a plataforma |
| 403 | 10009005 | API não assinada | Solicite a assinatura do endpoint chamado |
| 429 | 10009006 | Limite de taxa excedido, ou aplicação em bloqueio temporário | Aguarde o Retry-After e repita; se ainda for rejeitado, recue exponencialmente (comece em 1 s, dobre até 30 s, adicione jitter); os limites valem por aplicação e por grupo de endpoints, regras e cabeçalhos em Limite de taxa e backoff |
| 413 | 10009027 | Corpo da requisição acima do limite de tamanho do gateway | Envie corpos menores; na verificação de NF-e, envie uma única NF-e de até 1 MB |
Os links de download (linkDanfe, linkDownloadXml, linkDacce, nfeLinkXml, cteLinkDacte, dceLinkDace e similares) são requisições GET simples sem cabeçalhos de assinatura; suas falhas são status HTTP com o envelope da plataforma, veja Download de arquivos:
| HTTP | code | Significado | Ação |
|---|---|---|---|
| 401 | 10009035 | Link de download inválido (caminho alterado, token reutilizado ou assinatura divergente) | Use o link exatamente como devolvido pela API de consulta |
| 401 | 10009036 | Link de download expirado | Consulte o documento novamente para obter um link novo |
| 503 | 10009037 | Arquivo ainda não pronto | Repita o mesmo link após Retry-After |
| 404 | 10013011 | Arquivo não encontrado | Verifique a origem do link |
| 429 | 10013016 | Downloads em excesso de um mesmo IP por links de callback | Repita após Retry-After |
Validação de requisição e falhas da plataforma
| code | HTTP | Formato | Cenário | Ação |
|---|---|---|---|---|
| 10001001 | 400 | Array | Falha na validação de campos da requisição, uma entrada por campo; também erros de contrato de registro / atualização da seção emissaoDCe (os dois blocos de configuração ausentes, atualização alterando cnpj / município, redução do cursor da série, troca de série) | Corrija conforme mensagem |
| 10001000 | 500 | Array ou objeto simples | Falha do lado da plataforma; endpoints de formato array, verificação e consulta cadastral podem devolvê-la | Repita com backoff; se persistir, contate a plataforma com o timestamp e o path da requisição |
Empresas e certificados
Formato array. Veja Empresas.
| codigo | HTTP | Cenário | Ação |
|---|---|---|---|
| 10003004 | 400 | Registro: cidade / estado não resolvidos para um código IBGE; emissão: código IBGE do município do destinatário inexistente ou inconsistente com uf | Verifique a UF e o nome da cidade / código IBGE |
| 10003008 | 400 | Senha do certificado incorreta | Verifique a senha |
| 10003000 | 404 | empresaId inexistente ou não pertence a esta aplicação | Verifique o empresaId |
| 10003002 | 400 | CNPJ já registrado | A empresa existe; use o empresaId original |
| 10003006 | 400 | Dados de registro sem a IE | Informe inscricaoEstadual |
| 10003010 | 400 | CNPJ do certificado não corresponde à empresa | Use o certificado correto |
| 10003011 | 400 | Certificado expirado | Use um certificado válido |
| 10003012 | 400 | Certificado idêntico ao atualmente ativo | Nada a enviar |
| 10003050 | 400 | Cadastro automático: CNPJ não encontrado nos dados cadastrais públicos | Confira o CNPJ |
| 10003051 | 503 | Cadastro automático: dados cadastrais públicos indisponíveis | Repita a mesma requisição mais tarde |
| 10003052 | 400 | Regime tributário da empresa pendente de confirmação (cadastro automático); não emite novos documentos | Envie optanteSimplesNacional e mei em Registrar empresa com id |
| 10003053 | 400 | Cadastro automático: estado ou município do endereço não identificado | Use o endpoint de cadastro de empresa |
| 10009033 | 400 | Registro de webhook inválido (id divergente / contentType não JSON / código desconhecido em eventos) | Corrija conforme indicado, veja Registrar webhook |
| 10009010 | 400 | URL de callback inválida; só endereços http / https | Use um endereço público https |
| 10009013 | 400 | URL de callback aponta para rede interna ou reservada | Use um endereço público |
| 10009019 | 400 | URL de callback longa demais | Encurte a URL |
Classes de imposto
Formato de array. Classe inexistente é HTTP 404, alteração simultânea é HTTP 409, o resto HTTP 400. Todos os códigos em Classes de imposto.
| Código de erro | HTTP | Cenário | Ação |
|---|---|---|---|
| 10005200 | 404 | Código inexistente ou excluído | Verifique o código e empresaId |
| 10005203 | 400 | Código de tributação não suportado | Corrija conforme as tabelas de códigos em Emitir NF-e |
| 10005204 | 400 | A classificação não pertence ao CST | Os três primeiros dígitos da classificação devem ser o CST |
| 10005206 | 409 | Classe alterada ao mesmo tempo | Consulte de novo e reenvie |
| 10005208 | 400 | codigo no corpo da criação ou da substituição inteira | Remova codigo: a plataforma gera o código, devolve na criação e ele vai no caminho depois |
| 10005210 | 400 | Campo desconhecido no corpo; mensagem aponta o caminho | Remova o campo; os nomes válidos estão na página do endpoint |
| 10005211 | 400 | Duas linhas do mesmo grupo com a mesma combinação de cenario, tipoPessoa e naoContribuinte | Junte ou remova uma das linhas |
| 10005212 | 400 | Primeiro dígito do cfop da linha diferente do cenário | Ajuste o CFOP ao cenário: saída 5 / 6 / 7, entrada 1 / 2 / 3 |
| 10005213 | 400 | Número ou booleano enviado como texto; mensagem aponta o caminho | Envie números como número JSON e booleanos como true / false |
| 10005214 | 400 | CFOP fora do grupo: ISSQN só com 5933, ICMS nunca com 5933 | Ajuste o CFOP ao grupo |
| 10005216 | 400 | tipo diferente do atual na atualização | O tipo não muda; crie outra classe |
| 10005217 | 400 | Classe NFCe com campo que a emissão de NFC-e não tem; mensagem aponta o caminho | Remova o campo, ou crie uma classe NFe |
| 10005218 | 400 | Grupo que o tipo não admite: issqn em NFe, ipi em NFCe | Remova o grupo |
| 10005219 | 400 | Classe NFCe com cenário fora de SaidaDentroEstado / Padrao | Ajuste o cenário |
| 10004047 | 400 | Linha de ICMS de não contribuinte ou pessoa física com código só de contribuinte (10, 30, 70, 101, 201, 202, 203) ou percentualCreditoSimples | Use 102 / 500 ou outro código, ou retire a dimensão |
| 10005008 | 400 | Linha de PIS / COFINS 01 com aliquota diferente da alíquota legal do regime de PIS/COFINS configurado na empresa | Use a alíquota legal ou omita; veja «Regime tributário» em Empresas |
| 10004046 | 400 | Código incompatível com o regime da empresa (CRT 1/4 exige CSOSN de 3 dígitos, CRT 2/3 CST de 2 dígitos) | Ajuste o código ao regime da empresa |
NF-e
Formato array. Erros de negócio são HTTP 400; documento desconhecido é HTTP 404 com codigo 10004000 ou 10004001. Rejeições da SEFAZ durante a emissão não são erros HTTP: aparecem como status Negada na consulta e como webhook invoice.rejected. Veja NF-e.
| codigo | HTTP | Cenário | Ação |
|---|---|---|---|
| 10004000 / 10004001 | 404 | O nfeId da consulta / cancelamento / carta de correção não existe | Verifique o id enviado na emissão e o empresaId |
| 10004002 | 400 | Tarefas de emissão pendentes em excesso para o CNPJ | Repita mais tarde |
| 10004004 | 400 | Empresa não apta a emitir (ainda não aprovada ou certificado não pronto) | Aguarde a aprovação / vincule o certificado |
| 10004012 | 400 | Cancelamento / carta de correção: nota não está autorizada | Consulte para confirmar o status |
| 10004013 | 400 | Cancelamento: fora da janela de 24 horas | Emita uma nota de devolução |
| 10004014 | 400 | Cancelamento: recusado pela SEFAZ (código de status e motivo anexados) | Atue conforme o motivo da SEFAZ |
| 10004015 | 400 | Carta de correção: já há 20 cartas registradas na nota | Sem novas cartas; cancele e reemita ou emita nota de devolução |
| 10004016 | 400 | Carta de correção recusada pela SEFAZ (código de status e motivo anexados) | Atue conforme o motivo da SEFAZ |
| 10004017 | 400 | Carta de correção: menos de 15 caracteres após a sanitização | Reescreva em português / ASCII |
| 10004019 | 400 | Carta de correção: fora da janela de 720 horas após a autorização | Apenas cancelar e reemitir ou nota de devolução |
| 10004021 a 10004026 | 400 | Referências da nota de devolução: referência ausente / referência em nota que não é de devolução / original não encontrada ou de outra empresa / original não autorizada / item original não encontrado / quantidade acima da linha original | Veja as regras de nota de devolução em Emitir NF-e |
| 10004030 | 400 | ambienteEmissao não corresponde ao ambiente atual da empresa | Envie no ambiente da empresa ou peça à operação a troca, veja Ambientes |
| 10004031 | 400 | Valor não suportado (presencaConsumidor / múltiplos pagamentos / tipo de pagamento desconhecido / tipoPessoa inconsistente com o documento / comprador CPF com inscricaoEstadual) | Ajuste ao escopo suportado em Emitir NF-e |
| 10004034 | 400 | Comprador CNPJ sem cliente.inscricaoEstadual | Envie a inscrição estadual do comprador (contribuinte de ICMS) |
| 10004043 | 400 | Campo de contrato ausente (redução de base / margem e alíquota de ST / diferimento / valor de tributo por unidade / código de IPI / pCredSN ausente na requisição e no perfil); mensagem indica o caminho do campo | Preencha o campo conforme a matriz de códigos tributários em Emitir NF-e |
| 10004044 | 400 | Campo não aplicável ao código tributário (substituicaoTributaria em código sem ST, percentualCreditoSimples em código sem crédito) | Remova o grupo |
| 10004045 | 400 | cliente.inscricaoEstadual do comprador CNPJ não passa na regra de dígito verificador do estado do comprador (a SEFAZ rejeitaria com 209 após a numeração) | Verifique a IE e o estado do comprador |
| 10004046 | 400 | Código tributário não corresponde ao regime da empresa (CRT 1/4 exige CSOSN de 3 dígitos, CRT 2/3 CST de 2 dígitos) | Use a família de códigos do regime da empresa |
| 10004047 | 400 | Comprador não contribuinte com código exclusivo de contribuinte (10/30/70, 101/201/202/203) ou com pCredSN | Use 102 / 500 ou 900 sem crédito |
| 10004051 | 400 | Código IBGE ausente e não foi possível completá-lo pelo CEP: CEP fora da base, ligado a mais de um município ou de outro estado | Envie o código IBGE ou verifique cep / uf |
| 10005000 | 400 | Rejeitado pelo motor tributário (regime / código tributário incompatível, código de ST para comprador não contribuinte, alíquota fora da faixa) | Veja as regras de parâmetros tributários em Emitir NF-e |
| 10005007 | 400 | Empresa CRT 3 sem alíquota de PIS / COFINS no CST 01 e sem regime de PIS/COFINS configurado: a plataforma não tem como preencher | Envie aliquota ou configure o regime no console, em «Dados tributários»; veja Empresas |
| 10005008 | 400 | Empresa CRT 3 com alíquota de PIS / COFINS no CST 01 diferente da legal do regime de PIS/COFINS | Use a alíquota legal ou omita; veja Empresas |
| 10005202 | 400 | A classe de imposto referenciada na linha não existe, foi excluída ou é de outra empresa | Verifique classeImposto e empresaId, veja Classes de imposto |
| 10005215 | 400 | Classe de outro tipo: a NF-e só referencia classe NFe e a NFC-e só classe NFCe | Referencie uma classe do tipo certo |
| 10005220 | 400 | A classe referenciada está incompatível com o regime atual da empresa (IncompativelComRegime) | Substitua a classe inteira pelo regime novo, veja Classes de imposto |
| 10001002 | 400 | Linha com classeImposto que envia icms ou issqn sem cfop | Envie cfop nessa linha |
| 10005209 | 400 | A classe referenciada não tem linha para esta nota num grupo que a linha precisa (ICMS ou ISSQN da linha de serviço, PIS, COFINS); mensagem diz o grupo, o cenário, o tipo de cliente e se o comprador é não contribuinte | Acrescente uma linha à classe, ou envie o grupo na requisição; veja a ordem de escolha em Classes de imposto |
NFC-e
Formato array. Erros de negócio são HTTP 400; documento ou empresa desconhecidos são HTTP 404. Rejeições da SEFAZ não são erros HTTP: aparecem como status Negada na consulta e como webhook nfce.rejected. Veja NFC-e.
| codigo | HTTP | Cenário | Ação |
|---|---|---|---|
| 10022006 | 404 | nfceId não existe | Confira o id e o empresaId |
| 10003000 | 404 | empresaId não existe | Confira o empresaId |
| 10022001 | 400 | NFC-e não habilitada no ambiente atual da empresa | Envie esse ambiente em emissaoNFeConsumidor no registro ou na atualização |
| 10022002 | 400 | A empresa não pode emitir (não aprovada ou certificado indisponível) | Aguarde a aprovação ou envie o certificado |
| 10022003 | 400 | ambienteEmissao diferente do ambiente atual da empresa | Envie no ambiente da empresa |
| 10022004 | 400 | Viola uma regra da NFC-e; mensagem diz qual | Corrija, ou emita uma NF-e |
| 10022007 | 400 | Prazo de cancelamento expirado (30 minutos no cancelamento, 168 horas na substituição) | Siga a regra do estado e emita uma NF-e de estorno |
| 10022008 | 400 | O status não permite (não autorizada, cancelamento em andamento) | Consulte para confirmar o status |
| 10022009 | 400 | O estado exige QR Code v2 e a empresa não tem CSC utilizável | O QR Code v2 é ativado pela plataforma e o CSC só vale em produção; fale com a plataforma |
| 10022024 | 400 | Código IBGE ausente e não foi possível completá-lo pelo CEP: CEP fora da base, ligado a mais de um município ou de outro estado | Envie o código IBGE ou verifique cep / uf |
| 10001001 | 400 | Falha na validação de campos | Corrija conforme mensagem |
| 10005000 | 400 | O motor tributário recusou a requisição | Corrija conforme mensagem |
| 10005007 | 400 | Empresa CRT 3 sem alíquota de PIS / COFINS no CST 01 e sem regime de PIS/COFINS configurado: a plataforma não tem como preencher | Envie aliquota ou configure o regime no console, em «Dados tributários»; veja Empresas |
| 10005008 | 400 | Empresa CRT 3 com alíquota de PIS / COFINS no CST 01 diferente da legal do regime de PIS/COFINS | Use a alíquota legal ou omita; veja Empresas |
| 10005202 | 400 | A classe de imposto referenciada na linha não existe, foi excluída ou é de outra empresa | Verifique classeImposto e empresaId, veja Classes de imposto |
| 10005215 | 400 | Classe de outro tipo: a NF-e só referencia classe NFe e a NFC-e só classe NFCe | Referencie uma classe do tipo certo |
| 10005220 | 400 | A classe referenciada está incompatível com o regime atual da empresa (IncompativelComRegime) | Substitua a classe inteira pelo regime novo, veja Classes de imposto |
| 10001002 | 400 | Linha com classeImposto que envia icms ou issqn sem cfop | Envie cfop nessa linha |
| 10005209 | 400 | A classe referenciada não tem linha para esta nota num grupo que a linha precisa (ICMS ou ISSQN da linha de serviço, PIS, COFINS); mensagem diz o grupo, o cenário, o tipo de cliente e se o comprador é não contribuinte | Acrescente uma linha à classe, ou envie o grupo na requisição; veja a ordem de escolha em Classes de imposto |
| 10005205 | 400 | A linha escolhida da classe tem um grupo ou campo que a NFC-e não aceita; mensagem aponta o campo | Crie uma classe própria para a NFC-e, ou envie esse grupo na requisição |
Motivos comuns de 10022004: presença não permitida; local de entrega ou retirada fora do estado, ou comprador contribuinte; valor acima do limite; falta identificação; entrega sem transportadora ou endereço, ou transportadora ou frete em venda sem entrega; entrega não permitida no estado; CFOP ou código tributário fora da lista da NFC-e; pagamento insuficiente, troco errado ou SemPagamento, ou terminal de cartão ou descrição em tipo de pagamento que não os aceita; campos que a NFC-e não aceita (todos listados de uma vez); nomes de valor desconhecidos.
Rejeições comuns da SEFAZ (repetidas como vêm em motivoStatus): 704 emissão mais de 5 minutos antes do recebimento pela SEFAZ; 717 presença não permitida; 725 CFOP não permitido; 750 limite de identificação atingido sem identificar o consumidor; 780 acima do limite do estado; 785 / 786 / 787 / 788 entrega não permitida no estado, entrega sem transportadora, sem consumidor, sem endereço; 462 / 463 / 464 CSC não cadastrado, revogado, QR Code não confere; 865 pagamentos abaixo do total da nota.
NFC-e offline
Veja NFC-e offline.
Endpoints
Envelope da plataforma. Erros de negócio voltam com HTTP 200 e success = false; empresa ou dispositivo inexistente volta com HTTP 404; validação de campo com HTTP 400.
| Código de erro | HTTP | Cenário | Ação |
|---|---|---|---|
| 10029100 | 404 | Empresa inexistente ou de outro integrador | Confira o empresaId |
| 10029202 | 404 | Dispositivo inexistente ou de outra empresa | Confira o dispositivoId |
| 10029101 | 200 | A empresa não pode emitir NFC-e: ainda não aprovada pela plataforma, reprovada ou desativada, sem NFC-e habilitada no ambiente escolhido, ou sem certificado A1 válido em produção; message diz o motivo | Empresa recém-cadastrada: aguarde a aprovação da plataforma antes de habilitar a emissão offline e gerar códigos de pareamento; reprovada: corrija conforme o motivo e envie de novo; envie emissaoNFeConsumidor no registro; vincule um certificado válido |
| 10029104 | 200 | Emissão offline da empresa desativada pela plataforma | Fale com a plataforma |
| 10029201 | 200 | A empresa já tem 20 códigos de pareamento pendentes | Use-os ou espere vencerem |
| 10029219 | 200 | ambiente diferente do ambiente atual da empresa | Gere o código no ambiente atual da empresa |
| 10029221 | 200 | serie entre 890 e 999; a NFC-e de emitente CNPJ só usa as séries 0 a 889 | Use uma série de 0 a 889 |
| 10029222 | 200 | serie é a série NFC-e do perfil da empresa em algum dos ambientes | Escolha outra série |
| 10029223 | 200 | serie já está com outro dispositivo ativo ou com um código pendente da empresa; message diz qual | Escolha outra série |
| 10029224 | 200 | numeroInicial não é maior que o maior número conhecido na série; message traz esse número | Envie um número inicial maior, ou omita para continuar depois desse número |
| 10029225 | 200 | serie pertence a um dispositivo desativado ou revogado que ainda tem notas offline a transmitir | Gere o código depois que o dispositivo anterior terminar de transmitir |
| 10029001 | 200 | Valor de parâmetro fora do permitido; message aponta o campo | Corrija para um valor permitido |
| 10001001 | 400 | Validação de campo da requisição | Corrija conforme message |
Pareamento de dispositivos
Devolvidos pela plataforma no pareamento pelo Assistente Fiscal ou pelo SDK; o assistente de instalação e a exceção do SDK mostram o código sem alteração.
| Código de erro | Cenário | Ação |
|---|---|---|
| 10029203 / 10029204 | Dispositivo desativado / revogado pela plataforma | Gere um novo código de pareamento |
| 10029205 | Código de pareamento inválido | Verifique se foi copiado inteiro; se preciso, gere outro |
| 10029206 / 10029207 / 10029208 | Código de pareamento vencido / já usado / cancelado | Gere um novo código de pareamento |
| 10029209 | O código não permite essa forma (por exemplo, código Assistente usado pelo SDK) | Gere outro conforme a forma de integração |
| 10029210 | Pareamento pelo SDK sem o nome do PDV | Informe o nome do PDV na inicialização |
| 10029501 | Software do PDV bloqueado pela plataforma | Fale com a plataforma |
| 10029211 | Versão do PDV bloqueada ou abaixo da mínima | Atualize o PDV |
| 10029212 | Versão do núcleo desatualizada | Atualize o Assistente Fiscal ou o SDK |
| 10029213 | CNPJ do certificado diferente da empresa | Use o certificado A1 da empresa |
| 10029214 | Certificado vencido | Troque por um certificado válido |
| 10029219 | Ambiente do código diferente do ambiente atual da empresa (conferido de novo no pareamento) | Gere um novo código no ambiente atual da empresa |
| 10029221 a 10029225 | A série do dispositivo indicada no código é conferida de novo no pareamento e não está mais disponível; mesmo significado que na geração do código | Gere um novo código com outra série ou outro número inicial |
| 10029307 | Ambiente do dispositivo diferente do ambiente atual da empresa: depois da mudança de ambiente, a emissão online e a transmissão do dispositivo antigo são recusadas | Gere um código no ambiente atual, pareie um dispositivo novo e desative o antigo |
| 10029424 | Número já usado na emissão online do dispositivo; devolvido quando o núcleo descartou o número, tentou de novo uma vez e o conflito continua | O banco local e os registros da plataforma divergem; exporte os logs e fale com a plataforma |
| 10029426 | Na emissão online do dispositivo, o mesmo id já tem uma nota não rejeitada na plataforma | Confira a nota original; use um id novo para uma venda nova |
Núcleo de emissão offline e SDK
O Assistente Fiscal e o SDK embarcado usam o mesmo núcleo de emissão offline. No SDK os erros do núcleo são lançados como exceção (Codigo é o código de erro e Tipo a constante); na interface local do Assistente vêm em codigo. As faixas 10029800 e 10029780 vêm do núcleo, e a faixa 10029870 do SDK e da comunicação com o runtime; códigos que só aparecem por defeito do próprio SDK não estão listados aqui, veja a Referência do SDK. Códigos de erro devolvidos pela plataforma são repassados sem alteração.
| Código de erro | Constante | Cenário | Ação |
|---|---|---|---|
| 10029780 | ENGINE_TAX_CLASS_REQUIRES_ONLINE | Linha de item referencia classe de imposto, mas não foi possível acessar a plataforma para expandi-la; nenhum número consumido; o Assistente Fiscal responde HTTP 400 | Reenvie com o mesmo id quando a rede voltar; sem rede, envie impostos nas linhas de item, veja Classe de imposto e conexão |
| 10029801 | ENGINE_NOT_ACTIVATED | Empresa não pareada neste computador, ou nenhuma empresa pareada ainda | Conduza o pareamento; com várias empresas, confira empresaId |
| 10029802 | ENGINE_EMPRESA_REQUIRED | Várias empresas pareadas, mas empresaId não informado | Informe empresaId |
| 10029803 | ENGINE_LICENSE_MISSING | Não há licença para emissão offline | Sincronize uma vez com rede (SincronizarAgora) |
| 10029804 | ENGINE_LICENSE_EXPIRED | Licença vencida; a emissão offline é recusada e a online segue normal | Restaure a rede; a renovação é automática |
| 10029805 | ENGINE_LICENSE_SIGNATURE_INVALID | Assinatura da licença inválida | Ação manual: fale com a plataforma, a base local pode ter sido adulterada |
| 10029806 | ENGINE_LICENSE_NOT_FOR_DEVICE | A licença não pertence a este dispositivo | Ação manual: pareie de novo |
| 10029807 | ENGINE_OFFLINE_WINDOW_CLOSED | O prazo da emissão offline terminou | Restaure a rede e emita online |
| 10029808 | ENGINE_LICENSE_QUOTA_EXHAUSTED | A série do dispositivo chegou ao número 999999999 | Desative o dispositivo e pareie-o de novo com um código de pareamento novo que informe outra série em serie; a plataforma não troca a série sozinha |
| 10029809 | ENGINE_CLOCK_ROLLBACK | O relógio do sistema foi atrasado | Ação manual: corrija a hora do sistema |
| 10029810 | ENGINE_TRANSMISSION_DEADLINE_REACHED | A nota pendente mais antiga passou do prazo de transmissão | Ação manual: restaure a rede e transmita o quanto antes |
| 10029811 | ENGINE_OFFLINE_NOT_ALLOWED | A empresa ou o estado não permite emissão offline; ou a base acabou de ser restaurada de um backup e ainda não recebeu uma nova licença | Só é possível emitir online; depois de restaurar, a emissão offline volta sozinha após uma sincronização com a plataforma |
| 10029812 | ENGINE_OFFLINE_FUEL_NOT_SUPPORTED | Nota com combustível não pode ser emitida offline | Emita quando a rede voltar |
| 10029813 | ENGINE_CERTIFICATE_UNAVAILABLE | Certificado não encontrado, sem chave privada ou com CNPJ divergente | Ação manual: confira o repositório de certificados; se preciso, TrocarCertificado |
| 10029814 | ENGINE_CERTIFICATE_EXPIRED | Certificado vencido | Ação manual: renove e chame TrocarCertificado |
| 10029815 | ENGINE_SNAPSHOT_MISSING | Configuração local ou dados fiscais ausentes ou com falha de verificação | Sincronize com rede; se persistir, fale com a plataforma |
| 10029816 | ENGINE_DEVICE_DEACTIVATED | Dispositivo desativado | Ação manual: fale com o integrador; as notas offline já emitidas seguem sendo transmitidas |
| 10029817 | ENGINE_REQUEST_INVALID | Falha na validação da requisição; Detalhes lista os motivos campo a campo | Corrija a requisição; dá para validar antes com Previsualizar |
| 10029818 | ENGINE_DUPLICATE_ID_DIFFERENT_CONTENT | O mesmo id já foi usado em nota de conteúdo diferente | Venda nova com id novo; para repetir, use a requisição original e recupere a nota original |
| 10029819 | ENGINE_NOTE_NOT_FOUND | A nota não existe neste computador | Confira id e empresaId |
| 10029820 | ENGINE_NOTE_NOT_CORRECTABLE | A situação atual não permite correção | Só Rejeitada pode usar Substituir |
| 10029821 | ENGINE_CORRECTION_CHANGES_TOTALS | A correção alterou valores ou tributos | Altere só o que não envolve valores |
| 10029822 | ENGINE_CANCEL_NOT_ALLOWED | A situação atual não permite cancelar; no cancelamento por substituição, a nota original não é uma nota normal emitida online (nota offline, já cancelada ou com cancelamento pendente) | Não tente de novo |
| 10029823 | ENGINE_SERIE_EXHAUSTED | Numeração da série do dispositivo esgotada | Desative o dispositivo e pareie-o de novo com um código de pareamento novo que informe outra série em serie; a plataforma não troca a série sozinha |
| 10029824 | ENGINE_PLATFORM_UNREACHABLE | Operação que exige rede (pareamento) sem conexão com a plataforma | Confira a rede e tente de novo |
| 10029825 | ENGINE_ACTIVATION_CODE_INVALID | Formato, assinatura ou validade do código de pareamento incorretos | Ação manual: gere outro código de pareamento |
| 10029826 | ENGINE_ACTIVATION_HOST_UNTRUSTED | O código de pareamento aponta para um endereço de plataforma não confiável | Ação manual: confirme a origem do código e o ambiente do instalador (homologação / produção) |
| 10029827 | ENGINE_KEY_PROTECTION_FAILED | O diretório de dados veio de outro computador ou de outro usuário do Windows | Ação manual: rode no computador e com o usuário originais, ou pareie de novo |
| 10029828 | ENGINE_DATA_DIR_LOCKED | Diretório de dados em uso por outro processo, inclusive, ao restaurar um backup, uma instância deste programa em que ainda não se chamou Encerrar | Feche a outra instância; antes de restaurar um backup, chame Encerrar |
| 10029829 | ENGINE_LOCAL_STORE_CORRUPTED | Base local inconsistente | Ação manual: não apague o diretório de dados, fale com a plataforma |
| 10029830 | ENGINE_PROTOCOL_VERSION_UNSUPPORTED | Versões do SDK e do runtime incompatíveis | Atualize SDK e runtime juntos |
| 10029831 | ENGINE_RUNTIME_START_FAILED | O runtime não iniciou | Confira se o diretório do runtime está completo e se o antivírus está bloqueando |
| 10029832 | ENGINE_RUNTIME_CRASHED | O runtime saiu inesperadamente | Pode tentar de novo; com reinício automático o SDK se recupera sozinho; reenvie a emissão com o mesmo id |
| 10029833 | ENGINE_TIMEOUT | Tempo de espera esgotado | Reenvie a emissão com o mesmo id, ou faça Consultar antes |
| 10029834 | ENGINE_SHUTTING_DOWN | Encerrando ou já encerrado | Chame Iniciar de novo |
| 10029835 | ENGINE_IN_PROCESS_UNSUPPORTED | O modo em processo do Java exige Java 21 ou superior | Use o modo subprocesso |
| 10029836 | ENGINE_INTERNAL_ERROR | Erro interno do núcleo; a descrição traz um número de referência | Fale com a plataforma informando o número de referência e o log |
| 10029837 | ENGINE_ALREADY_ACTIVATED | Empresa já pareada neste diretório de dados | Não precisa parear de novo; para trocar de dispositivo, desative o antigo antes |
| 10029838 | ENGINE_PLATFORM_RESPONSE_UNTRUSTED | Falha na verificação da resposta da plataforma; os dados anteriores foram mantidos | Nova tentativa automática depois; se persistir, verifique se um proxy de rede alterou a resposta |
| 10029839 | ENGINE_ACTIVATION_PERSIST_FAILED | Pareada na plataforma, mas a gravação local falhou | Pareie de novo com o mesmo código de pareamento |
| 10029840 | ENGINE_CONFIG_INVALID | Configuração de inicialização inválida | Corrija a configuração |
| 10029841 | ENGINE_AUTHORIZED_XML_UNAVAILABLE | XML autorizado indisponível: ainda não autorizada, ou ausente neste computador e não recuperável da plataforma | Aguarde o evento de autorização e leia de novo; se não for possível recuperar, tente mais tarde |
| 10029842 | ENGINE_LOCAL_STORE_NEWER_VERSION | O diretório de dados foi usado por uma versão mais nova e o núcleo se recusa a iniciar; a interface local do Assistente Fiscal devolve HTTP 503 | Instale ou atualize para uma versão igual ou superior à última usada; não apague o diretório de dados |
| 10029843 | ENGINE_CANCEL_XML_UNAVAILABLE | XML de cancelamento indisponível: ainda não cancelada, ou ausente neste computador e não recuperável da plataforma | Aguarde o evento de cancelamento concluído e leia de novo; se não for possível recuperar, tente mais tarde |
| 10029844 | ENGINE_EXPORT_FAILED | Falha ao gravar o arquivo da exportação ou do backup: destino sem permissão de escrita, ou arquivo de backup já existente | Troque o diretório ou o nome do arquivo; confira espaço em disco e permissões |
| 10029845 | ENGINE_SUBSTITUTE_KEY_INVALID | No cancelamento por substituição, a chave da nota substituta é inválida, ou não é uma nota offline não rejeitada deste dispositivo e desta empresa | Informe a chave de 44 dígitos da nota offline emitida por este dispositivo para a mesma venda |
| 10029846 | ENGINE_BACKUP_INVALID | O backup não pode ser restaurado: senha errada, ou o arquivo de backup foi alterado, está corrompido ou não é um backup da emissão offline; o Assistente Fiscal responde HTTP 400 | Confira a senha do backup; use outro backup íntegro. A base original fica inalterada |
| 10029874 | ENGINE_PARAMS_INVALID | Parâmetro ausente ou de tipo errado; Detalhes.campo indica o parâmetro | Corrija o parâmetro, por exemplo requisição que não é objeto JSON, formato da impressão digital do certificado ou formato de data |
| 10029877 | ENGINE_RUNTIME_NOT_FOUND | Runtime não encontrado | Confira o instalador e o diretório do runtime |
| 10029878 | ENGINE_TOO_MANY_PENDING | Mais de 64 chamadas aguardando ao mesmo tempo | Reduza a concorrência |
| 10029880 | ENGINE_PRINCIPAL_UNREACHABLE | Um secundário no modo principal e secundário não alcança o principal; o pedido não chegou | Tente depois, ou passe o caixa para a máquina reserva |
| 10029881 | ENGINE_PRINCIPAL_RESULT_UNKNOWN | O pedido chegou ao principal, mas a resposta não voltou; resultado desconhecido | Com o principal de volta, consulte pelo mesmo id; reemitir com o mesmo id e conteúdo não emite duas vezes |
| 10029882 | ENGINE_TERMINAL_TOKEN_INVALID | Token do terminal secundário inválido ou revogado | Emita outro token no principal e atualize a configuração do secundário |
| 10029883 | ENGINE_PRINCIPAL_ADDRESS_INVALID | Endereço do principal mal formatado ou fora da rede local privada | Corrija o endereço do principal na configuração do secundário |
| 10029884 | ENGINE_MODE_METHOD_UNAVAILABLE | O modo atual não oferece esse método | Pareamento, troca de certificado, backup e exportação são feitos no principal; gestão de terminais só no principal |
| 10029885 | ENGINE_PRINCIPAL_REJECTED | O principal recusou a origem do pedido, por exemplo um secundário fora das redes permitidas | Confira as redes permitidas do principal e a rede |
| 10029886 | ENGINE_PRINCIPAL_RATE_LIMITED | Falhas de autenticação demais; limitado pelo principal | Confira o token e tente após 1 minuto |
| 10029887 | ENGINE_PRINCIPAL_LISTEN_FAILED | Não foi possível escutar na porta de rede local do principal | Troque a porta do principal ou libere a porta |
| 10029888 | ENGINE_TERMINAL_NOT_FOUND | O terminal a revogar não existe | Confira o identificador do terminal |
Assistente Fiscal
| Código de erro | HTTP | Cenário | Ação |
|---|---|---|---|
| 10029900 | 401 | Token de caixa ausente | Envie Authorization: Bearer tfl_… |
| 10029901 | 401 | Token de caixa inválido ou revogado | O gerente gera um novo token |
| 10029902 | 403 | O token não tem acesso a essa empresa | Gere um token que inclua essa empresa |
| 10029903 | 403 | Origem fora das redes permitidas do modo rede local | Confira as configurações do modo rede local |
| 10029904 | 400 | Endereço de callback inválido | Só http / https; com o modo rede local desligado, só endereço de loopback |
| 10029905 | 401 | A ação do programa de desktop exige sessão de gerente | Entre com o PIN de gerente |
| 10029906 | 401 | PIN de gerente errado | Digite de novo; 5 erros no total bloqueiam |
| 10029907 | 409 | Impressora indisponível | Verifique a conexão da impressora e a impressora escolhida em Configurações |
| 10029908 | 409 | Assistente de instalação não concluído | Conclua primeiro o assistente de instalação |
| 10029909 | 400 | Requisição inválida | Corrija conforme mensagem |
| 10029910 | 404 | Recurso inexistente | Confira o caminho |
| 10029911 | 400 | Formato de PIN inválido; deve ter de 6 a 8 dígitos | Defina de novo nesse formato |
| 10029912 | 500 | Erro interno do assistente | Exporte o pacote de diagnóstico e fale com a plataforma |
| 10029913 | 403 | Cabeçalho Host da requisição do programa de desktop não permitido; só 127.0.0.1, localhost ou [::1] com a porta do assistente | Abra o programa de desktop em http://127.0.0.1:porta, sem proxy nem outro nome de host |
| 10029914 | 429 | Erros de PIN demais; bloqueado | Espere o fim do bloqueio, veja as perguntas frequentes do Assistente Fiscal |
| 10029916 | 409 | Porta escolhida ocupada ou sem como escutar; configuração não alterada | Escolha outra porta |
| 10029917 | 403 | A sessão de caixa não tem acesso a esta empresa | Entre com o PIN de gerente para fazer a operação |
| 10029918 | 429 | Assistente ocupado: já há 3 recuperações de XML em andamento, ou já há uma exportação ou um backup em andamento | Tente mais tarde, sem repetir a chamada seguidamente |
| 10029919 | 400 | Configuração de proxy de saída inválida | Em «Configurações» do programa de desktop, corrija «Conexão com a internet» e «Endereço» do proxy de saída conforme indicado; a configuração não foi salva |
| 10029920 | 409 | Ao salvar o proxy de saída ou restaurar a partir de backup é preciso reiniciar o núcleo de emissão, mas há exportação, backup ou download de XML em andamento que não terminou em 15 segundos | Espere essas operações terminarem e salve ou restaure de novo; nem a configuração nem a base local foram alteradas |
| 10029922 | 409 | Espaço livre inferior a 256 MB no disco do diretório de dados do assistente; exportação, backup ou upload de arquivo de backup recusado | Libere espaço nesse disco e tente de novo |
| 10029923 | 403 | Requisição do programa de desktop sem token anti-CSRF ou com token errado; comum quando a sessão expirou ou a página ficou aberta por muito tempo | Atualize a página; se persistir, entre de novo com o PIN do gerente |
| 10029924 | 429 | Sessões de caixa abertas com frequência excessiva; no máximo 20 por minuto a partir da mesma origem | Espere um minuto e entre de novo na página de emissão |
Os erros do Assistente Fiscal só aparecem na interface local do assistente e no programa de desktop; o SDK embarcado não os devolve; de 10029905 a 10029908, 10029911, de 10029913 a 10029917 e de 10029919 a 10029924 só aparecem no programa de desktop.
CT-e
Formato array. Erros de negócio são HTTP 400; documento / tarefa inexistente é HTTP 404 com codigo 10017002 ou 10017003. Rejeições da SEFAZ durante a emissão aparecem como status Negada na consulta e como webhook cte.rejected. Veja CT-e.
| codigo | HTTP | Cenário | Ação |
|---|---|---|---|
| 10017002 / 10017003 | 404 | cteId não encontrado ou não pertence à empresa | Verifique o id e o empresaId |
| 10003000 | 404 | empresaId não encontrado | Verifique o empresaId |
| 10017004 | 400 | Empresa não pode emitir (não aprovada / certificado não pronto) | Aguarde a aprovação / vincule o certificado |
| 10017005 / 10017006 | 400 | Requisição duplicada concorrente / tarefas pendentes em excesso para o CNPJ | Repita mais tarde |
| 10017007 | 400 | Série numérica não resolvida (nenhuma configurada, ou várias ativas sem escolha) | Configure uma série do modelo 57 |
| 10017010 | 400 | ambienteEmissao diferente do ambiente da empresa | Envie para o ambiente da empresa |
| 10017011 | 400 | Código IBGE do município não encontrado | Verifique codigoIbge |
| 10017050 | 400 | codigoIbge ausente e não foi possível completá-lo pelo CEP: cep ausente, fora da base ou ligado a mais de um município | Envie codigoIbge ou verifique cep |
| 10017012 / 10017013 | 400 | Participante ausente / tomador inconsistente com o indicador de IE | Adicione o participante ou altere indicadorIeTomador |
| 10017014 | 400 | Referências de documentos inválidas (ausentes, dígito verificador incorreto, grupos misturados, documentos anteriores inconsistentes com o tipo de serviço) | Ajuste as referências |
| 10017015 | 400 | Tipo de documento inconsistente com as referências (complementar / substituto) | Envie ctesComplementados / cteSubstituido conforme tipo |
| 10017016 | 400 | Componentes não somam o total, ou aReceber acima do total | Corrija os valores |
| 10017017 / 10017018 / 10017019 | 400 | RNTRC inválido / modal não suportado / enumeração ou formato inválido (mensagem indica o campo) | Corrija conforme mensagem |
| 10017020 a 10017025 | 400 | Parâmetro tributário ausente / não permitido / incompatível com o regime / icmsUfFim obrigatório / linha da tabela de alíquotas ausente / CST não suportado | Veja os parâmetros tributários em CT-e |
| 10017030 | 400 | Mesmo id com mensagem diferente | Use um novo id ou reenvie a mensagem original |
| 10017031 | 400 | Produção: já existe documento ativo / autorizado para o id | Consulte o original |
| 10017040 a 10017045 | 400 | Status não permite o evento / janela de cancelamento excedida / texto de evento inválido / SEFAZ rejeitou o evento / limite de sequência de correção / evento referenciado não encontrado | Veja as regras de cancelamento e eventos em CT-e |
| 10017048 / 10017049 | 400 | Cancelamento bloqueado por carta de correção registrada / carta de correção fora da janela de 720 horas | Veja as regras de cancelamento e eventos em CT-e |
| 10001001 | 400 | Falha na validação de campos da requisição (uma entrada por campo) | Corrija conforme mensagem |
DC-e
Formato array. Erros de negócio são HTTP 400; documento / tarefa inexistente é HTTP 404 com codigo 10019002 ou 10019003. Rejeições da SEFAZ durante a emissão aparecem como status Negada na consulta e como webhook dce.rejected; rejeições do cancelamento pela SEFAZ aparecem como dce.cancel_rejected. Veja DC-e.
| codigo | HTTP | Cenário | Ação |
|---|---|---|---|
| 10019002 / 10019003 | 404 | dceId não encontrado, não pertence à empresa, ou cancelamento solicitado antes de o documento ser materializado | Verifique o id e o empresaId; cancele documentos Pendente apenas após a autorização |
| 10003000 | 404 | empresaId não encontrado | Verifique o empresaId |
| 10019012 / 10019010 | 400 | Empresa não configurada para DC-e (falta tipoEmitente / série do modelo 99 / site de Marketplace), ou ambiente diferente do ambiente atual da empresa | Envie emissaoDCe no registro ou em uma atualização com id; envie para o ambiente atual da empresa e peça à operação a troca para produção |
| 10019014 | 400 | Empresa Marketplace / Carrier sem remetente | Adicione o remetente |
| 10019015 | 400 | remetente.endereco ausente | Adicione o endereço do remetente |
| 10019016 | 400 | Remetente brasileiro sem cpfCnpj | Adicione o documento do remetente |
| 10019004 | 400 | Empresa não pode emitir (não aprovada / certificado não pronto) | Aguarde a aprovação / vincule o certificado |
| 10019017 | 400 | Destinatário brasileiro sem cpfCnpj | Adicione o documento do destinatário |
| 10019011 | 400 | Código IBGE do município não encontrado ou inconsistente com uf | Verifique cidade / uf |
| 10019049 | 400 | Código IBGE ausente e não foi possível completá-lo pelo CEP: CEP fora da base, ligado a mais de um município ou de outro estado | Envie o código IBGE ou verifique cep / uf |
| 10019005 / 10019006 | 400 | Requisição duplicada concorrente / tarefas pendentes em excesso para o CNPJ | Repita mais tarde |
| 10019007 | 400 | Série numérica não resolvida (várias séries ativas) | Peça à operação para consolidar as séries |
| 10019013 | 400 | Tipo de emitente Carrier ainda não suportado para emissão | Use uma empresa Marketplace / OwnIssuer |
| 10019018 | 400 | Item inválido (tamanho do NCM, quantidade ≤ 0, preço unitário negativo) | Corrija conforme mensagem |
| 10019019 | 400 | Enumeração ou formato inválido (mensagem indica o campo: tipoPessoa, modalidade, dataEmissao, documentos, telefone, e-mail, remetente de emitente próprio diferente da empresa) | Corrija conforme mensagem |
| 10019020 | 400 | CNPJ da transportadora inválido | Corrija cnpjTransportadora |
| 10019021 | 400 | Informações adicionais longas demais | Encurte o texto |
| 10019022 | 400 | Quantidade ou documento inválido em autorizacaoDownloadXml; contém o próprio CNPJ do emitente; documento duplicado | Corrija a lista |
| 10019030 | 400 | Mesmo id com mensagem diferente | Use um novo id ou reenvie a mensagem original |
| 10019031 | 400 | Produção: já existe documento ativo / autorizado para o id | Consulte o original |
| 10019040 a 10019043 | 400 | Status não permite cancelamento / janela de 24 horas excedida / cancelamento já aceito / motivo inválido | Veja as regras de cancelamento em DC-e |
| 10019048 | 400 | dataEmissao fora da janela permitida (mais de 5 minutos à frente ou mais de 30 dias atrás; mensagem traz os limites atuais) | Use a hora atual ou omita dataEmissao |
| 10001001 | 400 | Falha na validação de campos da requisição (uma entrada por campo); erros de contrato de registro / atualização de emissaoDCe | Corrija conforme mensagem |
NFS-e
Formato de array [{codigo, mensagem}]; erros de negócio são HTTP 400 e documento inexistente é HTTP 404 com codigo 10018002 ou 10018003. A emissão é assíncrona: a recusa na aceitação é um erro HTTP síncrono, enquanto a recusa da autoridade aparece como consulta Negada mais o webhook nfse.rejected. Veja NFS-e.
| codigo | HTTP | Cenário | O que fazer |
|---|---|---|---|
| 10018001 | 400 | Validação de parâmetros recusada na aceitação; mensagem indica o motivo (trava de IBS/CBS ainda não vigente, emitente paulistano enviando ibsCbs, código ou restrição estrutural não atendida) | Corrija conforme a mensagem |
| 10018002 / 10018003 | 404 | Documento não encontrado: o nfseId não pertence a este emitente, ou a chave de entrada não está entre as notas recebidas dele | Confira nfseId / chaveAcesso contra empresaId |
| 10018004 | 400 | Emitente inapto (desativado / certificado inutilizável) | Verifique o status do emitente e o certificado |
| 10018005 | 400 | Emitente sem perfil de NFS-e; a mensagem aponta o dado que falta | Envie emissaoNFSe no cadastro ou atualize com id |
| 10018010 | 400 | O padrão de NFS-e do município ainda não é suportado | Esse município ainda não pode emitir, fale com a plataforma |
| 10018012 | 400 | Código de serviço fora da lista oficial LC 116 | Confira codigoTributacaoNacional |
| 10018013 | 400 | Documento do tomador inválido | Confira o CPF / CNPJ / NIF |
| 10018014 | 400 | Exportação de serviço sem país de destino | Informe servico.paisPrestacao |
| 10018015 | 400 | O documento substituído não pode ser substituído | Confira o status do documento substituído |
| 10018020 | 400 | Não foi possível determinar a alíquota do ISS (sem valor informado nem parâmetro municipal) | Envie servico.iss.aliquota ou o servico.codigoTributacaoMunicipal correto |
| 10018022 | 400 | Emitente do Simples não pode enviar a alíquota de ISS diretamente | Remova aliquota |
| 10018023 | 400 | A retenção federal não pode ser determinada; informe o seguinte ou envie os valores retidos: %s. %s lista de uma vez os caminhos de todos os campos que faltam: servico.retencoes.categoriaFederal, cliente.orgaoPublico, cliente.optanteSimplesNacional, servico.retencoes.modoContratacao, servico.retencoes.anexoSimples, servico.retencoes.inss/irrf/csll/pis/cofins | Informe os campos listados e reenvie, ou envie os valores retidos em servico.retencoes, zero quando não houver; se a lista citar servico.retencoes.inss/irrf/csll/pis/cofins, só os valores resolvem, caso de classificação do serviço que exige análise manual ou de emissão por esta empresa como tomadora ou intermediária |
| 10018030 / 10018031 | 400 | A mesma requisição já está em processamento / esse pedido já tem nota ou o mesmo id traz conteúdo diferente | Tente mais tarde; use outro número de pedido ou confira o conteúdo |
| 10018040 | 400 | Já há uma análise de cancelamento em andamento | Aguarde o veredito do município |
| 10018041 | 400 | O documento já foi substituído | Nenhuma outra operação é permitida |
| 10018042 | 400 | O status atual não permite este evento (cancelamento; manifestação: cancelada / substituída / já manifestada / este emitente não é tomador nem intermediário) | Confira o status; cada parte manifesta uma vez por nota |
| 10018063 | 400 | A mensagem do DPS não atende ao XSD oficial; o detalhe traz linha, coluna, chave do erro e nome do elemento | Em geral texto fora do Latin-1, endereço incompleto, ou valor fora da tabela oficial |
| 10018064 | 400 | A mensagem de evento da NFS-e não atende ao XSD oficial | Confira o tamanho de motivo (15-255), o valor de codigoMotivo e o conjunto de caracteres |
| 10018065 | 400 | Os dados de referência fiscal da NFS-e necessários para esta nota não foram importados; informe na requisição os campos após a seta ou importe os dados de referência: %s. %s lista cada item com uma seta para o campo da requisição que o substitui: retencao-federal -> servico.retencoes.inss/irrf/csll/pis/cofins, pis-cofins -> servico.pisCofins.aliquotaPis/aliquotaCofins, iss-local-incidencia -> servico.iss.municipioIncidencia.codigoIbge; só ocorre quando um item que a requisição não trouxe precisa ser consultado pela plataforma, e sempre na aceitação | Envie na requisição os campos após a seta, ou confirme com a plataforma que os dados foram importados; iss-local-incidencia aparece com local da prestação em outro município, e basta enviar servico.iss.municipioIncidencia |
| 10018066 | 400 | Código IBGE ausente e não foi possível completá-lo pelo CEP: CEP fora da base, ligado a mais de um município ou de outro estado | Envie o código IBGE ou verifique cep / uf |
E-mail de notas
Formato array. Erros de negócio são HTTP 400; não encontrado é HTTP 404; e-mail anterior da mesma nota ainda não finalizado é HTTP 409. Uma falha de envio não é erro HTTP: aparece como status Falha na consulta e como webhook email.failed. Veja E-mail de notas.
| Código | HTTP | Situação | Ação |
|---|---|---|---|
| 10003000 | 404 | empresaId inexistente | Verifique o empresaId |
| 10021001 | 404 | Modelo de e-mail inexistente ou de outro integrador | Verifique o templateId |
| 10021002 | 400 | Modelo desativado, ou tipo de documento do modelo diferente da nota | Use outro modelo ou ative-o |
| 10021003 | 400 | Modelo usa variável fora da lista permitida | Corrija conforme a enumeração de variáveis |
| 10021004 | 400 | HTML do modelo com conteúdo proibido ou corpo acima de 64 KB | Corrija nos pontos citados na mensagem |
| 10021005 | 400 | tipoDocumento não suportado na lista de modelos | Envie só NFe / NFSe / CTe / DCe |
| 10021010 | 404 | Nota inexistente ou de outra empresa | Verifique documentoId, tipoDocumento e empresaId |
| 10021011 | 400 | Nota ainda não autorizada, ou cancelada ou substituída | Envie após a autorização |
| 10021012 | 400 | Sem modelo padrão para este tipo de documento | Envie templateId ou defina um modelo padrão |
| 10021013 | 400 | Sem destinatário | Envie destinatarios |
| 10021015 | 409 | O e-mail anterior desta nota ainda não terminou | Aguarde Enviado ou Falha e reenvie com novo id |
| 10021020 | 404 | E-mail inexistente ou de outra empresa | Verifique emailId e empresaId |
| 10001001 | 400 | Falha na validação de campos da requisição (uma entrada por campo) | Corrija conforme mensagem |
Verificação de NF-e
Formato simples {code, message}, veja Verificação de NF-e. Os erros de requisição da verificação de XML e da consulta por chave são HTTP 400; a requisição nem chega à validação:
| code | Endpoint | Significado | Ação |
|---|---|---|---|
| 10015000 | Verificação de XML | Corpo da requisição vazio | Envie o XML no corpo |
| 10015001 | Verificação de XML | Corpo acima de 1 MB | Uma NF-e autêntica isolada nunca excede isso; verifique se não está encapsulando ou codificando duas vezes |
| 10015002 | Verificação de XML | DTD detectado (<!DOCTYPE) | Remova os DTDs |
| 10015003 | Verificação de XML | Codificação diferente de UTF-8 | Converta para UTF-8 antes de enviar |
| 10015005 | Verificação de XML | Descontinuado, não é mais retornado (antes: chave já enviada para verificação por outro integrador) | Nenhuma ação necessária: cada integrador pode verificar a mesma nota de forma independente |
| 10015104 | Consulta por chave | Chave malformada (tamanho / caracteres / dígito verificador) | Valide localmente primeiro: 44 dígitos; o último é um dígito verificador mod-11 |
| 10015004 | Consulta por chave | Nota não encontrada em nenhuma fonte | A chave é desconhecida para a plataforma e para a fonte oficial; confirme com o emitente |
Obtenção de DANFE
As falhas de Obter DANFE devolvem o status HTTP abaixo e um objeto simples {code, message}; os erros vêm em JSON mesmo quando a requisição traz Accept: application/pdf.
| code | HTTP | Significado | Ação |
|---|---|---|---|
| 10015104 | 400 | Chave malformada (tamanho / caracteres / dígito verificador) | Valide localmente primeiro: 44 dígitos; o último é um dígito verificador mod-11 |
| 10015300 | 404 | Sua conta não tem registro de verificação desta nota (a verificação feita por outro integrador não conta) | Envie a nota antes pela verificação de XML; não repita |
| 10015301 | 409 | Verificação ainda não concluída (PENDING_SEFAZ / VALIDATING) | Obtenha o PDF depois de receber invoice.verify.completed |
| 10015302 | 409 | O veredito atual não gera PDF (só VALIDATED e notas com status Cancelada geram) | Não repita |
| 10015303 | 409 | A plataforma não tem o XML original desta nota | Reenvie o mesmo XML sem alterações pela verificação de XML, sem forceRevalidate, e obtenha de novo |
| 10015304 | 503 | O XML original ainda está sendo arquivado | Repita após o Retry-After (5 segundos) |
| 10015305 | 503 | Geração ocupada ou temporariamente indisponível | Repita após o Retry-After |
| 10001000 | 500 | Erro interno da plataforma | Repita com backoff; se persistir, contate a plataforma com o timestamp e o path da requisição |
Erros de validação de nível 1
Devolvidos com HTTP 200 dentro de validation.errors[] da resposta da verificação de XML. Não são erros de transporte: a requisição teve sucesso, o documento falhou. Todos são bloqueantes (REJECTED terminal) exceto PROTOCOL_MISSING, que é um aviso.
errors[].code | Numérico | Significado |
|---|---|---|
XML_MALFORMED | 10015100 | Sintaxe XML inválida |
XSD_INVALID | 10015101 | Não segue o leiaute XSD da NF-e 4.00 |
SIGNATURE_INVALID | 10015102 | Falha na verificação da assinatura digital (conteúdo adulterado, ou certificado expirado no momento da assinatura) |
SIGNATURE_CERT_MISMATCH | 10015103 | CNPJ do certificado de assinatura não corresponde ao emitente |
ACCESS_KEY_INVALID | 10015104 | Estrutura / dígito verificador da chave inválidos |
ACCESS_KEY_MISMATCH | 10015105 | Segmentos da chave não correspondem aos campos do documento |
PROTOCOL_MISMATCH | 10015106 | Bloco de protocolo inconsistente com o documento |
PROTOCOL_MISSING | 10015107 | Sem nó de protocolo (aviso, não bloqueante) |
XML_VERSION_UNSUPPORTED | 10015108 | Versão do leiaute diferente de 4.00 |
Resultados de nível 2
Não são erros HTTP: chegam pelo webhook invoice.verify.completed.
validationStatus | Terminal | Ação |
|---|---|---|
VALIDATED | Sim | Seguro prosseguir (liberar mercadoria, liquidar) |
REJECTED | Sim | Não prossiga; reason explica o veredicto da SEFAZ (cancelada / denegada / inutilizada / não encontrada / protocolo divergente) |
VALIDATION_ERROR (status nulo) | Sim, repetível | Falha de verificação do lado da plataforma, não é um julgamento da nota; como qualquer veredito, é reutilizado por 24 horas, então reenvie depois com o cabeçalho forceRevalidate: true |
VALIDATION_ERROR (status Desconhecida) | Sim, repetir não muda o resultado | A SEFAZ não aceita consultas desta nota (por exemplo, cStat 526, emitida há muito tempo); não é um julgamento da nota nem significa que ela é falsa. O veredito é reutilizado, não há por que repetir; confirme por outros meios, se necessário |
Consulta cadastral
Formato simples {code, message}. Erros de formato e de dígito verificador são rejeitados localmente e nunca chegam à fonte upstream; não consomem cota e não são cobrados. Veja Consulta cadastral.
| code | HTTP | Responsável | Significado | Ação |
|---|---|---|---|---|
| 10016000 | 400 | Chamador | Formato de CPF inválido (11 dígitos obrigatórios) | Verifique caracteres de formatação ou tamanho incorreto |
| 10016001 | 400 | Chamador | Dígitos verificadores do CPF inválidos | Valide localmente com o algoritmo mod-11 primeiro |
| 10016002 | 400 | Chamador | Data de nascimento inválida (DDMMYYYY válido obrigatório) | Observe a ordem dia-mês-ano e que a data precisa existir |
| 10016003 | 400 | Chamador | CPF não encontrado | O CPF não existe, ou o CPF e a data de nascimento não conferem (indistinguível de propósito) |
| 10016004 | 451 | Terceiro (bloqueio legal upstream) | LGPD: menor de 16 anos (Lei Felca), titular menor de 16 anos | Dados legalmente retidos; não repita |
| 10016005 | 422 | Terceiro (bloqueio legal upstream) | LGPD: menor de idade, titular entre 16 e 17 anos | Dados legalmente retidos; não repita |
| 10016006 | 428 | Terceiro (bloqueio legal upstream) | LGPD: idade nao verificavel - informe a data de nascimento para completar a verificacao, idade não verificável | A plataforma já reverificou uma vez com a data de nascimento; não repita |
| 10016010 | 400 | Chamador | Formato de CNPJ inválido (14 dígitos obrigatórios) | Verifique caracteres de formatação |
| 10016011 | 400 | Chamador | Dígitos verificadores do CNPJ inválidos | Valide localmente com o algoritmo mod-11 primeiro |
| 10016012 | 400 | Chamador | CNPJ não encontrado | Não existe esse CNPJ no cadastro oficial |
| 10016020 | 503 | Terceiro (upstream indisponível) | Fonte de dados upstream temporariamente indisponível | Repita com backoff exponencial (comece em 1 s, dobre até 30 s, adicione jitter); contate a plataforma se persistir |
Orientações de tratamento
- 401 / 403: erros de configuração; corrija a credencial, a assinatura de API ou o relógio. Não repita sem alteração.
- 400 / 404: a requisição ou a regra de negócio; corrija conforme o código. Alguns códigos são transitórios e podem ser repetidos depois: 10004002, 10017005 / 10017006, 10019005 / 10019006.
- 422 / 428 / 451: bloqueios legais nas consultas cadastrais; repetir é inútil.
- 429: aguarde o
Retry-Aftere repita; se ainda for rejeitado, recue com atraso exponencial e jitter (comece em 1 s, dobre até 30 s); ignorar o 429 e reenviar sem parar leva a um bloqueio temporário, veja Limite de taxa e backoff. - 503: repita a mesma requisição ou link após
Retry-After(10009037, 10015304 / 10015305, 10016020). - 5xx: repita com backoff; se persistir, contate a plataforma com o
timestampe o path da requisição. errorTypedo envelope:1erro de API,2rejeição da SEFAZ,3falha de sistema (repetível),4falha de validação de campos (corrija a requisição).- Nunca reenvie às cegas um documento rejeitado:
NegadaeREJECTEDsão veredictos terminais; atue primeiro conforme o motivo da SEFAZ.
