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, links de download) | 401 / 403 / 404 / 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 e DCe0000x 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 |
| 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 |
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 (serviço de renderização ocupado) | 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 |
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 |
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; são rejeitados como proteção contra XXE |
| 10015003 | Verificação de XML | Codificação diferente de UTF-8 | Converta para UTF-8 antes de enviar |
| 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 | Não | Falha de verificação do lado da plataforma, não é um julgamento da nota; 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
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.