Erros

Todo erro tem o mesmo formato (codigo, mensagem e, na validação, erros; veja Formato dos erros). Programe contra o codigo, que é estável; a mensagem é para uma pessoa ler e pode mudar de redação.

Catálogo de códigos

HTTP codigo Significa O que fazer
401 nao_autorizado chave ausente, inválida, revogada ou vencida (a mesma resposta nos quatro casos) confira a chave; peça uma nova se foi revogada ou venceu. Não repita em laço
403 conta_inativa a conta foi desativada fale com o suporte
404 empresa_nao_encontrada o CNPJ não existe ou não é da sua conta (a mesma resposta) confira o CNPJ e a chave
404 nota_nao_encontrada não há nota com essa ref nessa empresa e nesse ambiente confira ref, cnpj_emitente e o ambiente atual da empresa
404 produto_nao_encontrado não há produto com esse SKU nessa empresa confira o SKU
404 webhook_nao_encontrado · entrega_nao_encontrada o webhook ou a entrega não existe nesta conta confira o id
404 nao_encontrado rota ou arquivo que não existe (ou XML/DANFE ainda não disponível) confira a URL; o XML só existe depois da autorização
405 metodo_nao_permitido o método HTTP não vale para esta rota confira o método na referência
409 ref_ja_utilizada a ref já pertence a uma nota com outro conteúdo se é a mesma venda, reenvie o conteúdo original; se é uma venda nova, use uma ref nova. status_atual diz em que estado está a nota
422 requisicao_invalida formato, campo desconhecido, dado faltando, valor que não fecha. Todos os problemas vêm em erros, por campo corrija os campos apontados e reenvie. Repetir igual não adianta
422 validacao_fiscal o cálculo ou a empresa não permitem emitir: total que não fecha, cenário tributário não suportado, certificado vencido, empresa inativa, produção bloqueada leia a mensagem (diz o que ajustar); corrija o cadastro ou os parâmetros fiscais
422 cnpj_emitente_obrigatorio a conta tem mais de uma empresa e você não disse qual envie cnpj_emitente
422 limite_de_empresas a conta já tem o máximo de empresas fale com o suporte para ampliar
422 limite_de_webhooks a conta já tem o máximo de endereços de webhook (10) remova um que não usa mais
422 numero_retroativo o próximo número informado para a série é menor ou igual ao maior já usado nela (a numeração não volta) use ao menos o minimo da resposta; número já usado não se reaproveita
429 limite_de_requisicoes estourou o limite por minuto espere o Retry-After (segundos) e repita
5xx erro_interno falha da plataforma tente de novo depois de alguns segundos (com a mesma ref, repetir é seguro). Se persistir, cite o X-Request-Id ao suporte

Quando repetir a chamada

Resposta Repetir?
falha de rede, tempo esgotado, 5xx, 429 sim, com espera crescente. No POST /nfe, com a mesma ref e o mesmo corpo (é idempotente)
401, 403, 404, 405 não: o problema é de chave, permissão ou endereço
409, 422 não, sem mudar nada: corrija o que foi apontado

Como ler um 422

erros é um objeto com o caminho de cada campo com problema e a lista de mensagens dele:

{
  "codigo": "requisicao_invalida",
  "mensagem": "O campo nome destinatario é obrigatório.",
  "erros": {
    "nome_destinatario": ["O campo nome destinatario é obrigatório."],
    "items.0.codigo_ncm": ["O campo items.0.codigo_ncm deve ter 8 dígitos."],
    "formas_pagamento.1.valor_pagamento": ["..."]
  }
}
  • items.0.codigo_ncm é o campo codigo_ncm do primeiro item (a contagem começa em 0).
  • Erros de importação de produtos citam a linha: "Linha 2: O campo NCM deve ter 8 dígitos." (a linha é a posição na lista, começando em 1).
  • Alguns erros não são de um campo, mas de uma regra: erros.faixa na inutilização, erros.nota num cancelamento fora do prazo, erros.ambiente com o que impede a produção, erros.certificado para um certificado recusado.
  • mensagem repete o primeiro erro, para registrar numa linha de log.

Recusa fiscal (validacao_fiscal)

Não é um defeito do JSON: o JSON está certo, mas o cálculo ou a empresa não permitem emitir. As mensagens dizem o que ajustar. As mais comuns:

Mensagem (resumo) O que fazer
Total calculado (X) difere do total informado (Y). os valores estão em centavos. Confira preços, quantidades, frete, desconto e IPI; ou omita valor_total
A soma das formas de pagamento (X) difere do valor da nota (Y). acerte os valor_pagamento
Com mais de uma forma de pagamento, informe o valor de cada uma. informe valor_pagamento em todas
Certificado A1 ... ausente ou vencido. envie um certificado válido (Empresas)
Emissão em produção bloqueada: as tabelas fiscais ... (FISCAL_RATES_VERIFIED). a plataforma ainda não liberou a produção; emita em homologação ou fale com o suporte
CSOSN 900 ... não é suportado (e similares) o cenário tributário (ICMS-ST como substituto, por exemplo) ainda não é coberto: veja Modo híbrido
NCM inválido no item ... o NCM tem de ter 8 dígitos
Vendedor industrial: cadastre ipi_cst/ipi_aliq ... empresa industrial exige a situação tributária e a alíquota do IPI no item
UF inválida ou sem tabela fiscal confira a UF do destinatário

Rejeições comuns da SEFAZ

Se a nota passa pela validação e a SEFAZ a rejeita, o status fica erro_autorizacao e a nota traz status_sefaz (o cStat) e mensagem_sefaz (o texto original). Ao conferir, o texto da SEFAZ é o que vale. Os códigos abaixo são a leitura habitual da tabela da SEFAZ:

status_sefaz Costuma indicar O que fazer
203 emissor não habilitado para emitir NF-e na UF o CNPJ/IE precisa estar credenciado para emitir NF-e na SEFAZ da UF (vale também em homologação em várias UFs)
209, 233, 234 inscrição estadual do emitente inválida, não cadastrada ou não vinculada ao CNPJ confira a ie da empresa (PATCH /empresas/{cnpj})
213 o CNPJ do certificado não é o da empresa envie o certificado correto
280 a 286 problema no certificado: inválido, vencido, sem CNPJ, cadeia não ICP-Brasil envie um e-CNPJ A1 ICP-Brasil válido
225 falha de schema XML é defeito do lado da plataforma: abra um chamado com o ref e o X-Request-Id
108, 109 serviço da SEFAZ paralisado nada a fazer: a plataforma tenta de novo sozinha por até 6 horas; a nota fica processando_autorizacao
204, 539 a SEFAZ já tem uma nota com esta chave tratado pela plataforma: ela consulta a chave e dá a nota por autorizada, sem emitir outra
110, 301, 302, 303 uso denegado o status fica denegado: o número foi consumido e a nota não vale. Fale com o contador; para vender de novo, use uma ref nova

Em caso de rejeição, corrija e reenvie na mesma ref: o número fiscal é o mesmo (rejeição não consome número) e o histórico fica coerente.

Problemas frequentes

A nota está em processando_autorizacao há muito tempo. A SEFAZ pode estar lenta ou fora do ar. A plataforma tenta de novo sozinha por até 6 horas e, depois de uma falha de comunicação, consulta a chave antes de reenviar (para nunca emitir duplicado). Consulte GET /nfe/{ref}: se mensagem trouxer uma falha de comunicação, é a SEFAZ. Não reenvie a mesma venda com ref nova: criaria uma segunda nota.

Recebi 401 e a chave é a mesma de ontem. A chave foi revogada ou venceu. Peça uma nova (e, na rotação, siga o passo a passo).

O webhook não chega. (1) Use POST /webhooks/{id}/teste e veja o resultado; (2) em GET /webhooks/{id}/entregas, confira ultimo_status_http e ultimo_erro; (3) o endereço precisa ser https e público (não localhost); (4) o seu servidor precisa responder 2xx em até 10 segundos; (5) confira se o ativo é true e se eventos inclui o evento esperado.

422 com codigo_municipio_destinatario. A API não conseguiu descobrir o município pelo CEP. Informe codigo_municipio_destinatario (código IBGE de 7 dígitos).

A mesma nota foi emitida duas vezes. Só acontece se você usou ref diferentes para a mesma venda. Com a mesma ref, repetir devolve sempre a mesma nota. Use um identificador estável da venda (o número do pedido) como ref.

Preciso corrigir o valor de uma nota autorizada. Valores e impostos não se corrigem com carta de correção. Dentro do prazo, cancele (Cancelar) e emita outra com ref nova; fora dele, é devolução ou estorno com o contador.