Códigos de erro

A API usa os códigos HTTP padrão e explica o erro no corpo da resposta.

Formato

{
  "error":  "Certificado digital A1 não cadastrado. Envie o arquivo .pfx e a senha em Empresas → detalhe → Certificado digital antes de emitir.",
  "codigo": "CERTIFICADO_AUSENTE"
}

Decida pelo codigo (feito para máquina); o texto é para exibir e pode mudar. O codigo só vem quando o erro tem um — as respostas sem código estão mais abaixo. A chave do texto ainda não é a mesma em toda resposta (inconsistência conhecida): a maioria vem em error; vêm em erro a autenticação (401), as validações da NFC-e acima de R$ 10 mil e o que cai no tratador geral (validação de parâmetros, banco, erro interno e, fora da NF-e, os bloqueios de certificado e de ambiente). Para exibir, leia error ?? erro.

Códigos HTTP

Código	Quando
200	OK
201	Criado
202	Aceito: o documento foi para a fila de autorização. O resultado da SEFAZ ou da prefeitura chega depois (veja abaixo)
400	Requisição inválida (JSON malformado, parâmetro fora do formato)
401	Não autenticado (token ausente, inválido, revogado ou expirado)
402	O plano não inclui o recurso (recurso_fora_do_plano)
403	Sem permissão (perfil só de leitura, token de parceiro fora das rotas dele, produção não liberada)
404	Recurso não encontrado
409	Conflito: número já ocupado na série, ou requisição idêntica ainda em processamento
422	Os dados não permitem emitir (certificado, série, regra fiscal conferida antes do envio)
429	Limite de requisições — ver Rate limits
500	Erro interno (a mensagem é genérica de propósito)
503	Serviço dependente indisponível (ex.: consulta de status da SEFAZ)

SEFAZ fora do ar não vira 503 na emissão de NFC-e

A NFC-e entra em contingência offline: a resposta é 202 com contingencia_offline: true, e a transmissão à SEFAZ acontece sozinha quando ela volta.

Códigos da API (codigo)

Conferidos no código em 24/09/2026, nas rotas de emissão, consulta e cancelamento.

Acesso e plano

codigo	HTTP	Quando
recurso_fora_do_plano	402	O plano não inclui o documento ou o serviço. motivo diz por quê: fora_do_plano, trial_expirado (acabou o teste de 7 dias), pessoa_fisica_sem_ie (conta por CPF sem inscrição estadual) ou pessoa_fisica (não existe para CPF). Traz também planos_que_incluem e upgrade_url
FREE_TIER_HOMOLOGACAO_ONLY	403	A empresa está configurada para produção, mas o plano (ou uma suspensão) só permite homologação
TOKEN_PARCEIRO_FORA_DE_ROTA	403	Token de parceiro usado fora de /api/v1/parceiro/* e /api/v1/integracao/* — use o token da própria empresa

Certificado digital A1

codigo	HTTP	Quando
CERTIFICADO_AUSENTE	422	Sem certificado cadastrado (arquivo .pfx e senha). Barrado antes da fila: nada vai à SEFAZ
CERTIFICADO_VENCIDO	422	Certificado vencido. Barrado antes da fila: nada vai à SEFAZ
CERTIFICADO_SENHA	422	A senha não abre o certificado. Aparece nas operações que assinam na hora (cancelar, inutilizar); na emissão, a nota fica com status: "erro" e codigo_status: "CERTIFICADO_SENHA"

Numeração e série (NF-e, NFC-e e CT-e)

codigo	HTTP	Quando
numero_ocupado	409	NF-e e NFC-e: o número informado já tem documento nesta série que não pode ser reemitido. Se estiver autorizado, use o próximo número; se estiver processando, aguarde e tente de novo
multiplas_series	422	Várias séries ativas para o modelo e nenhuma padrão: informe a série
serie_inativa	422	Série desativada
numeracao_externa	422	A série é de numeração externa: o número vem do seu sistema (ex.: ide.nNF)
serie_pessoa_fisica	422	CT-e por pessoa física (CPF) exige série entre 920 e 969
inutilizacao_indisponivel_pessoa_fisica	422	Não existe inutilização de numeração para CPF (o leiaute da SEFAZ só aceita CNPJ)

NFC-e acima de R$ 10.000

Texto em erro, com sucesso: false.

codigo	HTTP	Quando
identificacao_obrigatoria_acima_10mil	422	Venda acima de R$ 10.000 sem CPF/CNPJ ou sem o endereço completo do comprador. faltando lista o que falta
endereco_nao_resolvido_pelo_cep	422	O CEP não completou o endereço do comprador: mande o endereço em dest.enderDest
cpf_situacao_irregular	422	CPF do comprador com situação irregular na Receita (falecido, nulo ou cancelado de ofício). situacao traz o código e a descrição; a venda não é emitida

Tratador geral

Texto em erro.

codigo	HTTP	Quando
VALIDACAO	400	Corpo ou parâmetros fora do formato esperado
23505 · 23503 · 23P01	409	Conflito com um registro existente (código do banco, repassado)
23502 · 23514 · 22001	422	Campo obrigatório ausente, regra de validação do banco ou tamanho excedido
22P02	400	Formato de dado inválido
ERRO	4xx	Erro sem código específico
ERRO_INTERNO	500	Falha interna

Sem codigo

Trate pelo status HTTP.

HTTP	Quando
401	Token ausente, inválido, revogado ou expirado (texto em erro)
403	Perfil só de leitura tentando emitir ou cancelar (perfil diz qual), ou a empresa do token está inativa
409	Requisição idêntica ainda em processamento: repita em instantes com a mesma Idempotency-Key (Idempotência)

Rejeição da SEFAZ ou da prefeitura

Não é erro HTTP. A emissão responde 202 e o resultado chega depois:

• Na consulta do documento, status vira "rejeitada" (ou "denegada"), com o cStat em codigo_status e o motivo em motivo_status.
• No webhook, resultado vem "rejeitada" (ou "denegada"), com erro: { "origem": "sefaz", "codigo": "<cStat>", "mensagem": "<motivo>" }. Na NFS-e, origem é "prefeitura".

Códigos SEFAZ comuns (cStat)

cStat	Significado
100	Autorizado o uso da NF-e
101	Cancelamento de NF-e homologado
103	Lote recebido com sucesso
110	Uso denegado
135	Evento registrado e vinculado à NF-e
204	Rejeição: duplicidade de NF-e
217	Rejeição: NF-e não consta na base de dados da SEFAZ
225	Rejeição: falha no schema XML
539	Rejeição: duplicidade de NF-e com diferença na chave de acesso

Emissor Nacional da NFS-e

Os códigos do Emissor Nacional começam com E e aparecem no motivo (ex.: [E0312]). Os que já apareceram na prática:

Código	Significado
E0015	A data de competência não pode ser posterior à data de emissão
E0039	O município emissor ainda não está parametrizado no Emissor Nacional
E0120	Inscrição municipal do prestador em conflito com o Cadastro Nacional de Contribuintes (CNC)
E0310	Código de tributação nacional inexistente
E0312	O código de tributação nacional não é administrado pelo município do ISSQN na data de competência