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, CT-e, DC-e, registro de webhook	400 / 404	Array `[{codigo, mensagem}]`, uma entrada por problema	`codigo` (string)
Verificação de NF-e e consulta cadastral	400 / 422 / 428 / 451 / 500 / 503	Objeto simples `{code, message}`	`code` (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, GW001, CER0005, NFe0001, CTe0001, DCe0001, DCe0000x e NFSe0001 mantêm seus valores alfanuméricos; todos os demais valores de codigo são 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

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	Recue e repita (comece em 1 s, dobre até 30 s, adicione jitter); os limites valem por aplicação e por grupo de endpoints
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	Objeto simples	Falha do lado da plataforma em uma chamada de verificação ou consulta cadastral	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
`GW001`	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
`CER0005`	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
10009033	400	Registro de webhook inválido (`id` divergente / `contentType` não JSON)	Corrija conforme indicado, veja Registrar webhook

NF-e

Formato array. Erros de negócio são HTTP 400; documento desconhecido é HTTP 404 com codigo NFe0001. 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
`NFe0001`	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
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

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
10001001	400	Falha na validação de campos	Corrija conforme `mensagem`
10005000	400	O motor tributário recusou a requisição	Corrija conforme `mensagem`

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.

CT-e

Formato array. Erros de negócio são HTTP 400; documento / tarefa inexistente é HTTP 404 com codigo CTe0001. 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
`CTe0001`	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`
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 DCe0001. Casos com código de exemplo documentado mantêm esse código; todos os demais codigo são o código numérico da plataforma. 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
`DCe0001`	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`
`DCe00004`	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
`DCe00005`	400	Empresa Marketplace / Carrier sem `remetente`	Adicione o remetente
`DCe00006`	400	`remetente.endereco` ausente	Adicione o endereço do remetente
`DCe00007`	400	Remetente brasileiro sem `cpfCnpj`	Adicione o documento do remetente
`DCe00008`	400	Empresa não pode emitir (não aprovada / certificado não pronto)	Aguarde a aprovação / vincule o certificado
`DCe00009`	400	Destinatário brasileiro sem `cpfCnpj`	Adicione o documento do destinatário
`GW001`	400	Código IBGE do município não encontrado ou inconsistente com `uf`	Verifique `cidade` / `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 NFSe0001. 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`
`NFSe0001`	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`

Verificação de NF-e

Formato simples {code, message}, HTTP 400. A requisição nem chega à validação. Veja Verificação de NF-e.

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

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`	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`

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: recue com atraso exponencial e jitter (comece em 1 s, dobre até 30 s).
503: repita a mesma requisição ou link após Retry-After (10009037, 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.