TF Fiscal
Documentação

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:

CamadaHTTPFormatoCampo 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 / 503Envelope 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 webhook400 / 404 / 409 / 500Array [{codigo, mensagem}], uma entrada por problemacodigo (string)
Verificação de NF-e e consulta cadastral400 / 404 / 409 / 422 / 428 / 451 / 500 / 503Objeto simples {code, message}code (inteiro)
Endpoints da NFC-e offline200 / 400 / 404Envelope da plataforma; erros de negócio também em HTTP 200code (inteiro)
Interface local do Assistente Fiscal400 / 404 / 409 / 429 / 500 / 503; autenticação 401 / 403Erros de negócio em array [{codigo, mensagem}]; erros de autenticação no envelope da plataformacodigo / code
SDK embarcadonenhumCodigo e Tipo da exceçãoCodigo (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:

FaixaDomínio
10001xxxValidação de requisição e falhas da plataforma
10003xxxEmpresa e certificado
10004xxxEmissão, cancelamento e carta de correção de NF-e
10005xxxMotor tributário
10009xxxPlataforma aberta (autenticação, assinatura, limite de taxa, webhooks, links de download)
10013xxxDownload de arquivos
10015xxxVerificação de NF-e
10016xxxConsulta cadastral (CNPJ / CPF)
10017xxxCT-e
10018xxxNFS-e
10019xxxDC-e
10021xxxE-mail de notas
10022xxxNFC-e
10029xxxNFC-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.

HTTPcodeSignificadoAção
40110009000Cabeçalhos de assinatura ausentes (token / sign / timestamp)Envie os três cabeçalhos em toda requisição
40110009001Timestamp inválido ou desvio de relógio acima de ±300 sSincronize o relógio (NTP); gere o timestamp a cada requisição, nunca reutilize
40110009002Token inválidoVerifique o app_secret; se foi rotacionado, atualize a configuração
40110009003Assinatura divergenteRecalcule a assinatura; veja a lista de verificação em Autenticação
40310009004Aplicação desativadaContate a plataforma
40310009015Aplicação não efetiva (aguardando aprovação ou rejeitada)Aguarde a aprovação / contate a plataforma
40310009014Conta do integrador desativadaContate a plataforma
40310009005API não assinadaSolicite a assinatura do endpoint chamado
42910009006Limite de taxa excedido, ou aplicação em bloqueio temporárioAguarde 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
41310009027Corpo da requisição acima do limite de tamanho do gatewayEnvie 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:

HTTPcodeSignificadoAção
40110009035Link de download inválido (caminho alterado, token reutilizado ou assinatura divergente)Use o link exatamente como devolvido pela API de consulta
40110009036Link de download expiradoConsulte o documento novamente para obter um link novo
50310009037Arquivo ainda não prontoRepita o mesmo link após Retry-After
40410013011Arquivo não encontradoVerifique a origem do link
42910013016Downloads em excesso de um mesmo IP por links de callbackRepita após Retry-After

Validação de requisição e falhas da plataforma

codeHTTPFormatoCenárioAção
10001001400ArrayFalha 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
10001000500Array ou objeto simplesFalha do lado da plataforma; endpoints de formato array, verificação e consulta cadastral podem devolvê-laRepita com backoff; se persistir, contate a plataforma com o timestamp e o path da requisição

Empresas e certificados

Formato array. Veja Empresas.

codigoHTTPCenárioAção
10003004400Registro: 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 ufVerifique a UF e o nome da cidade / código IBGE
10003008400Senha do certificado incorretaVerifique a senha
10003000404empresaId inexistente ou não pertence a esta aplicaçãoVerifique o empresaId
10003002400CNPJ já registradoA empresa existe; use o empresaId original
10003006400Dados de registro sem a IEInforme inscricaoEstadual
10003010400CNPJ do certificado não corresponde à empresaUse o certificado correto
10003011400Certificado expiradoUse um certificado válido
10003012400Certificado idêntico ao atualmente ativoNada a enviar
10003050400Cadastro automático: CNPJ não encontrado nos dados cadastrais públicosConfira o CNPJ
10003051503Cadastro automático: dados cadastrais públicos indisponíveisRepita a mesma requisição mais tarde
10003052400Regime tributário da empresa pendente de confirmação (cadastro automático); não emite novos documentosEnvie optanteSimplesNacional e mei em Registrar empresa com id
10003053400Cadastro automático: estado ou município do endereço não identificadoUse o endpoint de cadastro de empresa
10009033400Registro de webhook inválido (id divergente / contentType não JSON / código desconhecido em eventos)Corrija conforme indicado, veja Registrar webhook
10009010400URL de callback inválida; só endereços http / httpsUse um endereço público https
10009013400URL de callback aponta para rede interna ou reservadaUse um endereço público
10009019400URL de callback longa demaisEncurte 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 erroHTTPCenárioAção
10005200404Código inexistente ou excluídoVerifique o código e empresaId
10005203400Código de tributação não suportadoCorrija conforme as tabelas de códigos em Emitir NF-e
10005204400A classificação não pertence ao CSTOs três primeiros dígitos da classificação devem ser o CST
10005206409Classe alterada ao mesmo tempoConsulte de novo e reenvie
10005208400codigo no corpo da criação ou da substituição inteiraRemova codigo: a plataforma gera o código, devolve na criação e ele vai no caminho depois
10005210400Campo desconhecido no corpo; mensagem aponta o caminhoRemova o campo; os nomes válidos estão na página do endpoint
10005211400Duas linhas do mesmo grupo com a mesma combinação de cenario, tipoPessoa e naoContribuinteJunte ou remova uma das linhas
10005212400Primeiro dígito do cfop da linha diferente do cenárioAjuste o CFOP ao cenário: saída 5 / 6 / 7, entrada 1 / 2 / 3
10005213400Número ou booleano enviado como texto; mensagem aponta o caminhoEnvie números como número JSON e booleanos como true / false
10005214400CFOP fora do grupo: ISSQN só com 5933, ICMS nunca com 5933Ajuste o CFOP ao grupo
10005216400tipo diferente do atual na atualizaçãoO tipo não muda; crie outra classe
10005217400Classe NFCe com campo que a emissão de NFC-e não tem; mensagem aponta o caminhoRemova o campo, ou crie uma classe NFe
10005218400Grupo que o tipo não admite: issqn em NFe, ipi em NFCeRemova o grupo
10005219400Classe NFCe com cenário fora de SaidaDentroEstado / PadraoAjuste o cenário
10004047400Linha de ICMS de não contribuinte ou pessoa física com código só de contribuinte (10, 30, 70, 101, 201, 202, 203) ou percentualCreditoSimplesUse 102 / 500 ou outro código, ou retire a dimensão
10005008400Linha de PIS / COFINS 01 com aliquota diferente da alíquota legal do regime de PIS/COFINS configurado na empresaUse a alíquota legal ou omita; veja «Regime tributário» em Empresas
10004046400Có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.

codigoHTTPCenárioAção
10004000 / 10004001404O nfeId da consulta / cancelamento / carta de correção não existeVerifique o id enviado na emissão e o empresaId
10004002400Tarefas de emissão pendentes em excesso para o CNPJRepita mais tarde
10004004400Empresa não apta a emitir (ainda não aprovada ou certificado não pronto)Aguarde a aprovação / vincule o certificado
10004012400Cancelamento / carta de correção: nota não está autorizadaConsulte para confirmar o status
10004013400Cancelamento: fora da janela de 24 horasEmita uma nota de devolução
10004014400Cancelamento: recusado pela SEFAZ (código de status e motivo anexados)Atue conforme o motivo da SEFAZ
10004015400Carta de correção: já há 20 cartas registradas na notaSem novas cartas; cancele e reemita ou emita nota de devolução
10004016400Carta de correção recusada pela SEFAZ (código de status e motivo anexados)Atue conforme o motivo da SEFAZ
10004017400Carta de correção: menos de 15 caracteres após a sanitizaçãoReescreva em português / ASCII
10004019400Carta de correção: fora da janela de 720 horas após a autorizaçãoApenas cancelar e reemitir ou nota de devolução
10004021 a 10004026400Referê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 originalVeja as regras de nota de devolução em Emitir NF-e
10004030400ambienteEmissao não corresponde ao ambiente atual da empresaEnvie no ambiente da empresa ou peça à operação a troca, veja Ambientes
10004031400Valor 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
10004034400Comprador CNPJ sem cliente.inscricaoEstadualEnvie a inscrição estadual do comprador (contribuinte de ICMS)
10004043400Campo 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 campoPreencha o campo conforme a matriz de códigos tributários em Emitir NF-e
10004044400Campo 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
10004045400cliente.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
10004046400Có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
10004047400Comprador não contribuinte com código exclusivo de contribuinte (10/30/70, 101/201/202/203) ou com pCredSNUse 102 / 500 ou 900 sem crédito
10004051400Có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 estadoEnvie o código IBGE ou verifique cep / uf
10005000400Rejeitado 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
10005007400Empresa CRT 3 sem alíquota de PIS / COFINS no CST 01 e sem regime de PIS/COFINS configurado: a plataforma não tem como preencherEnvie aliquota ou configure o regime no console, em «Dados tributários»; veja Empresas
10005008400Empresa CRT 3 com alíquota de PIS / COFINS no CST 01 diferente da legal do regime de PIS/COFINSUse a alíquota legal ou omita; veja Empresas
10005202400A classe de imposto referenciada na linha não existe, foi excluída ou é de outra empresaVerifique classeImposto e empresaId, veja Classes de imposto
10005215400Classe de outro tipo: a NF-e só referencia classe NFe e a NFC-e só classe NFCeReferencie uma classe do tipo certo
10005220400A classe referenciada está incompatível com o regime atual da empresa (IncompativelComRegime)Substitua a classe inteira pelo regime novo, veja Classes de imposto
10001002400Linha com classeImposto que envia icms ou issqn sem cfopEnvie cfop nessa linha
10005209400A 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 contribuinteAcrescente 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.

codigoHTTPCenárioAção
10022006404nfceId não existeConfira o id e o empresaId
10003000404empresaId não existeConfira o empresaId
10022001400NFC-e não habilitada no ambiente atual da empresaEnvie esse ambiente em emissaoNFeConsumidor no registro ou na atualização
10022002400A empresa não pode emitir (não aprovada ou certificado indisponível)Aguarde a aprovação ou envie o certificado
10022003400ambienteEmissao diferente do ambiente atual da empresaEnvie no ambiente da empresa
10022004400Viola uma regra da NFC-e; mensagem diz qualCorrija, ou emita uma NF-e
10022007400Prazo de cancelamento expirado (30 minutos no cancelamento, 168 horas na substituição)Siga a regra do estado e emita uma NF-e de estorno
10022008400O status não permite (não autorizada, cancelamento em andamento)Consulte para confirmar o status
10022009400O estado exige QR Code v2 e a empresa não tem CSC utilizávelO QR Code v2 é ativado pela plataforma e o CSC só vale em produção; fale com a plataforma
10022024400Có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 estadoEnvie o código IBGE ou verifique cep / uf
10001001400Falha na validação de camposCorrija conforme mensagem
10005000400O motor tributário recusou a requisiçãoCorrija conforme mensagem
10005007400Empresa CRT 3 sem alíquota de PIS / COFINS no CST 01 e sem regime de PIS/COFINS configurado: a plataforma não tem como preencherEnvie aliquota ou configure o regime no console, em «Dados tributários»; veja Empresas
10005008400Empresa CRT 3 com alíquota de PIS / COFINS no CST 01 diferente da legal do regime de PIS/COFINSUse a alíquota legal ou omita; veja Empresas
10005202400A classe de imposto referenciada na linha não existe, foi excluída ou é de outra empresaVerifique classeImposto e empresaId, veja Classes de imposto
10005215400Classe de outro tipo: a NF-e só referencia classe NFe e a NFC-e só classe NFCeReferencie uma classe do tipo certo
10005220400A classe referenciada está incompatível com o regime atual da empresa (IncompativelComRegime)Substitua a classe inteira pelo regime novo, veja Classes de imposto
10001002400Linha com classeImposto que envia icms ou issqn sem cfopEnvie cfop nessa linha
10005209400A 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 contribuinteAcrescente uma linha à classe, ou envie o grupo na requisição; veja a ordem de escolha em Classes de imposto
10005205400A linha escolhida da classe tem um grupo ou campo que a NFC-e não aceita; mensagem aponta o campoCrie 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 erroHTTPCenárioAção
10029100404Empresa inexistente ou de outro integradorConfira o empresaId
10029202404Dispositivo inexistente ou de outra empresaConfira o dispositivoId
10029101200A 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 motivoEmpresa 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
10029104200Emissão offline da empresa desativada pela plataformaFale com a plataforma
10029201200A empresa já tem 20 códigos de pareamento pendentesUse-os ou espere vencerem
10029219200ambiente diferente do ambiente atual da empresaGere o código no ambiente atual da empresa
10029221200serie entre 890 e 999; a NFC-e de emitente CNPJ só usa as séries 0 a 889Use uma série de 0 a 889
10029222200serie é a série NFC-e do perfil da empresa em algum dos ambientesEscolha outra série
10029223200serie já está com outro dispositivo ativo ou com um código pendente da empresa; message diz qualEscolha outra série
10029224200numeroInicial não é maior que o maior número conhecido na série; message traz esse númeroEnvie um número inicial maior, ou omita para continuar depois desse número
10029225200serie pertence a um dispositivo desativado ou revogado que ainda tem notas offline a transmitirGere o código depois que o dispositivo anterior terminar de transmitir
10029001200Valor de parâmetro fora do permitido; message aponta o campoCorrija para um valor permitido
10001001400Validação de campo da requisiçãoCorrija 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 erroCenárioAção
10029203 / 10029204Dispositivo desativado / revogado pela plataformaGere um novo código de pareamento
10029205Código de pareamento inválidoVerifique se foi copiado inteiro; se preciso, gere outro
10029206 / 10029207 / 10029208Código de pareamento vencido / já usado / canceladoGere um novo código de pareamento
10029209O código não permite essa forma (por exemplo, código Assistente usado pelo SDK)Gere outro conforme a forma de integração
10029210Pareamento pelo SDK sem o nome do PDVInforme o nome do PDV na inicialização
10029501Software do PDV bloqueado pela plataformaFale com a plataforma
10029211Versão do PDV bloqueada ou abaixo da mínimaAtualize o PDV
10029212Versão do núcleo desatualizadaAtualize o Assistente Fiscal ou o SDK
10029213CNPJ do certificado diferente da empresaUse o certificado A1 da empresa
10029214Certificado vencidoTroque por um certificado válido
10029219Ambiente 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 10029225A 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ódigoGere um novo código com outra série ou outro número inicial
10029307Ambiente 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 recusadasGere um código no ambiente atual, pareie um dispositivo novo e desative o antigo
10029424Nú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 continuaO banco local e os registros da plataforma divergem; exporte os logs e fale com a plataforma
10029426Na emissão online do dispositivo, o mesmo id já tem uma nota não rejeitada na plataformaConfira 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 erroConstanteCenárioAção
10029780ENGINE_TAX_CLASS_REQUIRES_ONLINELinha 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 400Reenvie com o mesmo id quando a rede voltar; sem rede, envie impostos nas linhas de item, veja Classe de imposto e conexão
10029801ENGINE_NOT_ACTIVATEDEmpresa não pareada neste computador, ou nenhuma empresa pareada aindaConduza o pareamento; com várias empresas, confira empresaId
10029802ENGINE_EMPRESA_REQUIREDVárias empresas pareadas, mas empresaId não informadoInforme empresaId
10029803ENGINE_LICENSE_MISSINGNão há licença para emissão offlineSincronize uma vez com rede (SincronizarAgora)
10029804ENGINE_LICENSE_EXPIREDLicença vencida; a emissão offline é recusada e a online segue normalRestaure a rede; a renovação é automática
10029805ENGINE_LICENSE_SIGNATURE_INVALIDAssinatura da licença inválidaAção manual: fale com a plataforma, a base local pode ter sido adulterada
10029806ENGINE_LICENSE_NOT_FOR_DEVICEA licença não pertence a este dispositivoAção manual: pareie de novo
10029807ENGINE_OFFLINE_WINDOW_CLOSEDO prazo da emissão offline terminouRestaure a rede e emita online
10029808ENGINE_LICENSE_QUOTA_EXHAUSTEDA série do dispositivo chegou ao número 999999999Desative 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
10029809ENGINE_CLOCK_ROLLBACKO relógio do sistema foi atrasadoAção manual: corrija a hora do sistema
10029810ENGINE_TRANSMISSION_DEADLINE_REACHEDA nota pendente mais antiga passou do prazo de transmissãoAção manual: restaure a rede e transmita o quanto antes
10029811ENGINE_OFFLINE_NOT_ALLOWEDA 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çaSó é possível emitir online; depois de restaurar, a emissão offline volta sozinha após uma sincronização com a plataforma
10029812ENGINE_OFFLINE_FUEL_NOT_SUPPORTEDNota com combustível não pode ser emitida offlineEmita quando a rede voltar
10029813ENGINE_CERTIFICATE_UNAVAILABLECertificado não encontrado, sem chave privada ou com CNPJ divergenteAção manual: confira o repositório de certificados; se preciso, TrocarCertificado
10029814ENGINE_CERTIFICATE_EXPIREDCertificado vencidoAção manual: renove e chame TrocarCertificado
10029815ENGINE_SNAPSHOT_MISSINGConfiguração local ou dados fiscais ausentes ou com falha de verificaçãoSincronize com rede; se persistir, fale com a plataforma
10029816ENGINE_DEVICE_DEACTIVATEDDispositivo desativadoAção manual: fale com o integrador; as notas offline já emitidas seguem sendo transmitidas
10029817ENGINE_REQUEST_INVALIDFalha na validação da requisição; Detalhes lista os motivos campo a campoCorrija a requisição; dá para validar antes com Previsualizar
10029818ENGINE_DUPLICATE_ID_DIFFERENT_CONTENTO mesmo id já foi usado em nota de conteúdo diferenteVenda nova com id novo; para repetir, use a requisição original e recupere a nota original
10029819ENGINE_NOTE_NOT_FOUNDA nota não existe neste computadorConfira id e empresaId
10029820ENGINE_NOTE_NOT_CORRECTABLEA situação atual não permite correçãoSó Rejeitada pode usar Substituir
10029821ENGINE_CORRECTION_CHANGES_TOTALSA correção alterou valores ou tributosAltere só o que não envolve valores
10029822ENGINE_CANCEL_NOT_ALLOWEDA 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
10029823ENGINE_SERIE_EXHAUSTEDNumeração da série do dispositivo esgotadaDesative 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
10029824ENGINE_PLATFORM_UNREACHABLEOperação que exige rede (pareamento) sem conexão com a plataformaConfira a rede e tente de novo
10029825ENGINE_ACTIVATION_CODE_INVALIDFormato, assinatura ou validade do código de pareamento incorretosAção manual: gere outro código de pareamento
10029826ENGINE_ACTIVATION_HOST_UNTRUSTEDO código de pareamento aponta para um endereço de plataforma não confiávelAção manual: confirme a origem do código e o ambiente do instalador (homologação / produção)
10029827ENGINE_KEY_PROTECTION_FAILEDO diretório de dados veio de outro computador ou de outro usuário do WindowsAção manual: rode no computador e com o usuário originais, ou pareie de novo
10029828ENGINE_DATA_DIR_LOCKEDDiretó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 EncerrarFeche a outra instância; antes de restaurar um backup, chame Encerrar
10029829ENGINE_LOCAL_STORE_CORRUPTEDBase local inconsistenteAção manual: não apague o diretório de dados, fale com a plataforma
10029830ENGINE_PROTOCOL_VERSION_UNSUPPORTEDVersões do SDK e do runtime incompatíveisAtualize SDK e runtime juntos
10029831ENGINE_RUNTIME_START_FAILEDO runtime não iniciouConfira se o diretório do runtime está completo e se o antivírus está bloqueando
10029832ENGINE_RUNTIME_CRASHEDO runtime saiu inesperadamentePode tentar de novo; com reinício automático o SDK se recupera sozinho; reenvie a emissão com o mesmo id
10029833ENGINE_TIMEOUTTempo de espera esgotadoReenvie a emissão com o mesmo id, ou faça Consultar antes
10029834ENGINE_SHUTTING_DOWNEncerrando ou já encerradoChame Iniciar de novo
10029835ENGINE_IN_PROCESS_UNSUPPORTEDO modo em processo do Java exige Java 21 ou superiorUse o modo subprocesso
10029836ENGINE_INTERNAL_ERRORErro interno do núcleo; a descrição traz um número de referênciaFale com a plataforma informando o número de referência e o log
10029837ENGINE_ALREADY_ACTIVATEDEmpresa já pareada neste diretório de dadosNão precisa parear de novo; para trocar de dispositivo, desative o antigo antes
10029838ENGINE_PLATFORM_RESPONSE_UNTRUSTEDFalha na verificação da resposta da plataforma; os dados anteriores foram mantidosNova tentativa automática depois; se persistir, verifique se um proxy de rede alterou a resposta
10029839ENGINE_ACTIVATION_PERSIST_FAILEDPareada na plataforma, mas a gravação local falhouPareie de novo com o mesmo código de pareamento
10029840ENGINE_CONFIG_INVALIDConfiguração de inicialização inválidaCorrija a configuração
10029841ENGINE_AUTHORIZED_XML_UNAVAILABLEXML autorizado indisponível: ainda não autorizada, ou ausente neste computador e não recuperável da plataformaAguarde o evento de autorização e leia de novo; se não for possível recuperar, tente mais tarde
10029842ENGINE_LOCAL_STORE_NEWER_VERSIONO 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 503Instale ou atualize para uma versão igual ou superior à última usada; não apague o diretório de dados
10029843ENGINE_CANCEL_XML_UNAVAILABLEXML de cancelamento indisponível: ainda não cancelada, ou ausente neste computador e não recuperável da plataformaAguarde o evento de cancelamento concluído e leia de novo; se não for possível recuperar, tente mais tarde
10029844ENGINE_EXPORT_FAILEDFalha ao gravar o arquivo da exportação ou do backup: destino sem permissão de escrita, ou arquivo de backup já existenteTroque o diretório ou o nome do arquivo; confira espaço em disco e permissões
10029845ENGINE_SUBSTITUTE_KEY_INVALIDNo cancelamento por substituição, a chave da nota substituta é inválida, ou não é uma nota offline não rejeitada deste dispositivo e desta empresaInforme a chave de 44 dígitos da nota offline emitida por este dispositivo para a mesma venda
10029846ENGINE_BACKUP_INVALIDO 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 400Confira a senha do backup; use outro backup íntegro. A base original fica inalterada
10029874ENGINE_PARAMS_INVALIDParâmetro ausente ou de tipo errado; Detalhes.campo indica o parâmetroCorrija o parâmetro, por exemplo requisição que não é objeto JSON, formato da impressão digital do certificado ou formato de data
10029877ENGINE_RUNTIME_NOT_FOUNDRuntime não encontradoConfira o instalador e o diretório do runtime
10029878ENGINE_TOO_MANY_PENDINGMais de 64 chamadas aguardando ao mesmo tempoReduza a concorrência
10029880ENGINE_PRINCIPAL_UNREACHABLEUm secundário no modo principal e secundário não alcança o principal; o pedido não chegouTente depois, ou passe o caixa para a máquina reserva
10029881ENGINE_PRINCIPAL_RESULT_UNKNOWNO pedido chegou ao principal, mas a resposta não voltou; resultado desconhecidoCom o principal de volta, consulte pelo mesmo id; reemitir com o mesmo id e conteúdo não emite duas vezes
10029882ENGINE_TERMINAL_TOKEN_INVALIDToken do terminal secundário inválido ou revogadoEmita outro token no principal e atualize a configuração do secundário
10029883ENGINE_PRINCIPAL_ADDRESS_INVALIDEndereço do principal mal formatado ou fora da rede local privadaCorrija o endereço do principal na configuração do secundário
10029884ENGINE_MODE_METHOD_UNAVAILABLEO modo atual não oferece esse métodoPareamento, troca de certificado, backup e exportação são feitos no principal; gestão de terminais só no principal
10029885ENGINE_PRINCIPAL_REJECTEDO principal recusou a origem do pedido, por exemplo um secundário fora das redes permitidasConfira as redes permitidas do principal e a rede
10029886ENGINE_PRINCIPAL_RATE_LIMITEDFalhas de autenticação demais; limitado pelo principalConfira o token e tente após 1 minuto
10029887ENGINE_PRINCIPAL_LISTEN_FAILEDNão foi possível escutar na porta de rede local do principalTroque a porta do principal ou libere a porta
10029888ENGINE_TERMINAL_NOT_FOUNDO terminal a revogar não existeConfira o identificador do terminal

Assistente Fiscal

Código de erroHTTPCenárioAção
10029900401Token de caixa ausenteEnvie Authorization: Bearer tfl_…
10029901401Token de caixa inválido ou revogadoO gerente gera um novo token
10029902403O token não tem acesso a essa empresaGere um token que inclua essa empresa
10029903403Origem fora das redes permitidas do modo rede localConfira as configurações do modo rede local
10029904400Endereço de callback inválidoSó http / https; com o modo rede local desligado, só endereço de loopback
10029905401A ação do programa de desktop exige sessão de gerenteEntre com o PIN de gerente
10029906401PIN de gerente erradoDigite de novo; 5 erros no total bloqueiam
10029907409Impressora indisponívelVerifique a conexão da impressora e a impressora escolhida em Configurações
10029908409Assistente de instalação não concluídoConclua primeiro o assistente de instalação
10029909400Requisição inválidaCorrija conforme mensagem
10029910404Recurso inexistenteConfira o caminho
10029911400Formato de PIN inválido; deve ter de 6 a 8 dígitosDefina de novo nesse formato
10029912500Erro interno do assistenteExporte o pacote de diagnóstico e fale com a plataforma
10029913403Cabeçalho Host da requisição do programa de desktop não permitido; só 127.0.0.1, localhost ou [::1] com a porta do assistenteAbra o programa de desktop em http://127.0.0.1:porta, sem proxy nem outro nome de host
10029914429Erros de PIN demais; bloqueadoEspere o fim do bloqueio, veja as perguntas frequentes do Assistente Fiscal
10029916409Porta escolhida ocupada ou sem como escutar; configuração não alteradaEscolha outra porta
10029917403A sessão de caixa não tem acesso a esta empresaEntre com o PIN de gerente para fazer a operação
10029918429Assistente ocupado: já há 3 recuperações de XML em andamento, ou já há uma exportação ou um backup em andamentoTente mais tarde, sem repetir a chamada seguidamente
10029919400Configuração de proxy de saída inválidaEm «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
10029920409Ao 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 segundosEspere essas operações terminarem e salve ou restaure de novo; nem a configuração nem a base local foram alteradas
10029922409Espaço livre inferior a 256 MB no disco do diretório de dados do assistente; exportação, backup ou upload de arquivo de backup recusadoLibere espaço nesse disco e tente de novo
10029923403Requisiçã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 tempoAtualize a página; se persistir, entre de novo com o PIN do gerente
10029924429Sessões de caixa abertas com frequência excessiva; no máximo 20 por minuto a partir da mesma origemEspere 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.

codigoHTTPCenárioAção
10017002 / 10017003404cteId não encontrado ou não pertence à empresaVerifique o id e o empresaId
10003000404empresaId não encontradoVerifique o empresaId
10017004400Empresa não pode emitir (não aprovada / certificado não pronto)Aguarde a aprovação / vincule o certificado
10017005 / 10017006400Requisição duplicada concorrente / tarefas pendentes em excesso para o CNPJRepita mais tarde
10017007400Série numérica não resolvida (nenhuma configurada, ou várias ativas sem escolha)Configure uma série do modelo 57
10017010400ambienteEmissao diferente do ambiente da empresaEnvie para o ambiente da empresa
10017011400Código IBGE do município não encontradoVerifique codigoIbge
10017050400codigoIbge ausente e não foi possível completá-lo pelo CEP: cep ausente, fora da base ou ligado a mais de um municípioEnvie codigoIbge ou verifique cep
10017012 / 10017013400Participante ausente / tomador inconsistente com o indicador de IEAdicione o participante ou altere indicadorIeTomador
10017014400Referê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
10017015400Tipo de documento inconsistente com as referências (complementar / substituto)Envie ctesComplementados / cteSubstituido conforme tipo
10017016400Componentes não somam o total, ou aReceber acima do totalCorrija os valores
10017017 / 10017018 / 10017019400RNTRC inválido / modal não suportado / enumeração ou formato inválido (mensagem indica o campo)Corrija conforme mensagem
10017020 a 10017025400Parâ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 suportadoVeja os parâmetros tributários em CT-e
10017030400Mesmo id com mensagem diferenteUse um novo id ou reenvie a mensagem original
10017031400Produção: já existe documento ativo / autorizado para o idConsulte o original
10017040 a 10017045400Status 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 encontradoVeja as regras de cancelamento e eventos em CT-e
10017048 / 10017049400Cancelamento bloqueado por carta de correção registrada / carta de correção fora da janela de 720 horasVeja as regras de cancelamento e eventos em CT-e
10001001400Falha 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.

codigoHTTPCenárioAção
10019002 / 10019003404dceId não encontrado, não pertence à empresa, ou cancelamento solicitado antes de o documento ser materializadoVerifique o id e o empresaId; cancele documentos Pendente apenas após a autorização
10003000404empresaId não encontradoVerifique o empresaId
10019012 / 10019010400Empresa não configurada para DC-e (falta tipoEmitente / série do modelo 99 / site de Marketplace), ou ambiente diferente do ambiente atual da empresaEnvie 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
10019014400Empresa Marketplace / Carrier sem remetenteAdicione o remetente
10019015400remetente.endereco ausenteAdicione o endereço do remetente
10019016400Remetente brasileiro sem cpfCnpjAdicione o documento do remetente
10019004400Empresa não pode emitir (não aprovada / certificado não pronto)Aguarde a aprovação / vincule o certificado
10019017400Destinatário brasileiro sem cpfCnpjAdicione o documento do destinatário
10019011400Código IBGE do município não encontrado ou inconsistente com ufVerifique cidade / uf
10019049400Có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 estadoEnvie o código IBGE ou verifique cep / uf
10019005 / 10019006400Requisição duplicada concorrente / tarefas pendentes em excesso para o CNPJRepita mais tarde
10019007400Série numérica não resolvida (várias séries ativas)Peça à operação para consolidar as séries
10019013400Tipo de emitente Carrier ainda não suportado para emissãoUse uma empresa Marketplace / OwnIssuer
10019018400Item inválido (tamanho do NCM, quantidade ≤ 0, preço unitário negativo)Corrija conforme mensagem
10019019400Enumeraçã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
10019020400CNPJ da transportadora inválidoCorrija cnpjTransportadora
10019021400Informações adicionais longas demaisEncurte o texto
10019022400Quantidade ou documento inválido em autorizacaoDownloadXml; contém o próprio CNPJ do emitente; documento duplicadoCorrija a lista
10019030400Mesmo id com mensagem diferenteUse um novo id ou reenvie a mensagem original
10019031400Produção: já existe documento ativo / autorizado para o idConsulte o original
10019040 a 10019043400Status não permite cancelamento / janela de 24 horas excedida / cancelamento já aceito / motivo inválidoVeja as regras de cancelamento em DC-e
10019048400dataEmissao 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
10001001400Falha na validação de campos da requisição (uma entrada por campo); erros de contrato de registro / atualização de emissaoDCeCorrija 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.

codigoHTTPCenárioO que fazer
10018001400Validaçã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 / 10018003404Documento não encontrado: o nfseId não pertence a este emitente, ou a chave de entrada não está entre as notas recebidas deleConfira nfseId / chaveAcesso contra empresaId
10018004400Emitente inapto (desativado / certificado inutilizável)Verifique o status do emitente e o certificado
10018005400Emitente sem perfil de NFS-e; a mensagem aponta o dado que faltaEnvie emissaoNFSe no cadastro ou atualize com id
10018010400O padrão de NFS-e do município ainda não é suportadoEsse município ainda não pode emitir, fale com a plataforma
10018012400Código de serviço fora da lista oficial LC 116Confira codigoTributacaoNacional
10018013400Documento do tomador inválidoConfira o CPF / CNPJ / NIF
10018014400Exportação de serviço sem país de destinoInforme servico.paisPrestacao
10018015400O documento substituído não pode ser substituídoConfira o status do documento substituído
10018020400Nã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
10018022400Emitente do Simples não pode enviar a alíquota de ISS diretamenteRemova aliquota
10018023400A 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/cofinsInforme 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 / 10018031400A mesma requisição já está em processamento / esse pedido já tem nota ou o mesmo id traz conteúdo diferenteTente mais tarde; use outro número de pedido ou confira o conteúdo
10018040400Já há uma análise de cancelamento em andamentoAguarde o veredito do município
10018041400O documento já foi substituídoNenhuma outra operação é permitida
10018042400O 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
10018063400A mensagem do DPS não atende ao XSD oficial; o detalhe traz linha, coluna, chave do erro e nome do elementoEm geral texto fora do Latin-1, endereço incompleto, ou valor fora da tabela oficial
10018064400A mensagem de evento da NFS-e não atende ao XSD oficialConfira o tamanho de motivo (15-255), o valor de codigoMotivo e o conjunto de caracteres
10018065400Os 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çãoEnvie 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
10018066400Có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 estadoEnvie 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ódigoHTTPSituaçãoAção
10003000404empresaId inexistenteVerifique o empresaId
10021001404Modelo de e-mail inexistente ou de outro integradorVerifique o templateId
10021002400Modelo desativado, ou tipo de documento do modelo diferente da notaUse outro modelo ou ative-o
10021003400Modelo usa variável fora da lista permitidaCorrija conforme a enumeração de variáveis
10021004400HTML do modelo com conteúdo proibido ou corpo acima de 64 KBCorrija nos pontos citados na mensagem
10021005400tipoDocumento não suportado na lista de modelosEnvie só NFe / NFSe / CTe / DCe
10021010404Nota inexistente ou de outra empresaVerifique documentoId, tipoDocumento e empresaId
10021011400Nota ainda não autorizada, ou cancelada ou substituídaEnvie após a autorização
10021012400Sem modelo padrão para este tipo de documentoEnvie templateId ou defina um modelo padrão
10021013400Sem destinatárioEnvie destinatarios
10021015409O e-mail anterior desta nota ainda não terminouAguarde Enviado ou Falha e reenvie com novo id
10021020404E-mail inexistente ou de outra empresaVerifique emailId e empresaId
10001001400Falha 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:

codeEndpointSignificadoAção
10015000Verificação de XMLCorpo da requisição vazioEnvie o XML no corpo
10015001Verificação de XMLCorpo acima de 1 MBUma NF-e autêntica isolada nunca excede isso; verifique se não está encapsulando ou codificando duas vezes
10015002Verificação de XMLDTD detectado (<!DOCTYPE)Remova os DTDs
10015003Verificação de XMLCodificação diferente de UTF-8Converta para UTF-8 antes de enviar
10015005Verificação de XMLDescontinuado, 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
10015104Consulta por chaveChave malformada (tamanho / caracteres / dígito verificador)Valide localmente primeiro: 44 dígitos; o último é um dígito verificador mod-11
10015004Consulta por chaveNota não encontrada em nenhuma fonteA 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.

codeHTTPSignificadoAção
10015104400Chave malformada (tamanho / caracteres / dígito verificador)Valide localmente primeiro: 44 dígitos; o último é um dígito verificador mod-11
10015300404Sua 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
10015301409Verificação ainda não concluída (PENDING_SEFAZ / VALIDATING)Obtenha o PDF depois de receber invoice.verify.completed
10015302409O veredito atual não gera PDF (só VALIDATED e notas com status Cancelada geram)Não repita
10015303409A plataforma não tem o XML original desta notaReenvie o mesmo XML sem alterações pela verificação de XML, sem forceRevalidate, e obtenha de novo
10015304503O XML original ainda está sendo arquivadoRepita após o Retry-After (5 segundos)
10015305503Geração ocupada ou temporariamente indisponívelRepita após o Retry-After
10001000500Erro interno da plataformaRepita 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[].codeNuméricoSignificado
XML_MALFORMED10015100Sintaxe XML inválida
XSD_INVALID10015101Não segue o leiaute XSD da NF-e 4.00
SIGNATURE_INVALID10015102Falha na verificação da assinatura digital (conteúdo adulterado, ou certificado expirado no momento da assinatura)
SIGNATURE_CERT_MISMATCH10015103CNPJ do certificado de assinatura não corresponde ao emitente
ACCESS_KEY_INVALID10015104Estrutura / dígito verificador da chave inválidos
ACCESS_KEY_MISMATCH10015105Segmentos da chave não correspondem aos campos do documento
PROTOCOL_MISMATCH10015106Bloco de protocolo inconsistente com o documento
PROTOCOL_MISSING10015107Sem nó de protocolo (aviso, não bloqueante)
XML_VERSION_UNSUPPORTED10015108Versão do leiaute diferente de 4.00

Resultados de nível 2

Não são erros HTTP: chegam pelo webhook invoice.verify.completed.

validationStatusTerminalAção
VALIDATEDSimSeguro prosseguir (liberar mercadoria, liquidar)
REJECTEDSimNão prossiga; reason explica o veredicto da SEFAZ (cancelada / denegada / inutilizada / não encontrada / protocolo divergente)
VALIDATION_ERROR (status nulo)Sim, repetívelFalha 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 resultadoA 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.

codeHTTPResponsávelSignificadoAção
10016000400ChamadorFormato de CPF inválido (11 dígitos obrigatórios)Verifique caracteres de formatação ou tamanho incorreto
10016001400ChamadorDígitos verificadores do CPF inválidosValide localmente com o algoritmo mod-11 primeiro
10016002400ChamadorData de nascimento inválida (DDMMYYYY válido obrigatório)Observe a ordem dia-mês-ano e que a data precisa existir
10016003400ChamadorCPF não encontradoO CPF não existe, ou o CPF e a data de nascimento não conferem (indistinguível de propósito)
10016004451Terceiro (bloqueio legal upstream)LGPD: menor de 16 anos (Lei Felca), titular menor de 16 anosDados legalmente retidos; não repita
10016005422Terceiro (bloqueio legal upstream)LGPD: menor de idade, titular entre 16 e 17 anosDados legalmente retidos; não repita
10016006428Terceiro (bloqueio legal upstream)LGPD: idade nao verificavel - informe a data de nascimento para completar a verificacao, idade não verificávelA plataforma já reverificou uma vez com a data de nascimento; não repita
10016010400ChamadorFormato de CNPJ inválido (14 dígitos obrigatórios)Verifique caracteres de formatação
10016011400ChamadorDígitos verificadores do CNPJ inválidosValide localmente com o algoritmo mod-11 primeiro
10016012400ChamadorCNPJ não encontradoNão existe esse CNPJ no cadastro oficial
10016020503Terceiro (upstream indisponível)Fonte de dados upstream temporariamente indisponívelRepita 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-After e 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 timestamp e o path da requisição.
  • errorType do envelope: 1 erro de API, 2 rejeição da SEFAZ, 3 falha de sistema (repetível), 4 falha de validação de campos (corrija a requisição).
  • Nunca reenvie às cegas um documento rejeitado: Negada e REJECTED são veredictos terminais; atue primeiro conforme o motivo da SEFAZ.