Códigos de erro

Quando uma NFS-e é rejeitada ou a chamada da API falha, a resposta traz erros estruturados. A Notare também classifica cada rejeição em uma categoria — você sabe na hora se precisa agir, se é problema de dado do cliente, ou se é falha temporária.

Formato do erro

Validação de schema (HTTP 400)

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    {
      "campo": "servico.aliquotaIssBp",
      "codigo": "VALUE_OUT_OF_RANGE",
      "mensagem": "deve ser maior ou igual a 0 e menor que 10000"
    }
  ]
}

Rejeição da NFS-e (no body do response do `POST /v1/nfse`)

{
  "id": "5fcb9e1d-...",
  "status": "rejeitada",
  "erros": [
    {
      "campo": "servico.itemListaServico",
      "codigo": "ITEM_INVALIDO",
      "mensagem": "Código da lista de serviços não possui desdobramento exigido",
      "sugestao": "Use formato com 5 dígitos (ex: 10701)"
    }
  ],
  "meta": { "tentativas": 1, "...": "..." }
}

Categorias

Toda rejeição é classificada automaticamente. Use a categoria pra rotear o erro pro fluxo certo no seu ERP.

Categoria	O que significa	Quem age	Retry?
`cliente`	Dado do request inválido (CPF, valor, item LC 116)	Você corrige no ERP	Sim, com dado corrigido
`autorizacao`	Permissão do contribuinte ausente (login, cadastro inativo)	Cliente regulariza no portal correspondente	Sim, após regularizar
`sequencia`	RPS/DPS fora de ordem	Notare ressincroniza automaticamente	Automático
`infraestrutura`	Falha transitória (timeout, 5xx)	Aguarde — Notare retenta	Automático com backoff
`adapter`	XML estrutural — possível bug Notare	Abra ticket no suporte	Após investigação
`desconhecida`	Código novo, ainda não mapeado	Abra ticket no suporte	Após mapeamento

Códigos por categoria

Cliente (mais comuns)

Código	Significado	Como corrigir
`CPFCNPJ_INVALIDO`	DV do CPF/CNPJ não bate	Verificar dígito verificador
`ITEM_INVALIDO`	Item LC 116 não reconhecido	Usar formato com desdobramento (`10701` em vez de `1.07`)
`ALIQUOTA_FAIXA`	Alíquota fora da faixa permitida pelo município	Faixa típica: 200–500 bp
`VALOR_ZERO`	Valor total da nota é zero	Informar `valorServicosCentavos > 0`
`CST_INCOMPATIVEL`	CST incompatível com a situação (ex: 400 imune com valor ISSRF)	Revisar combinação CST + valores
`CADASTRO_AUSENTE`	Tomador sem campos obrigatórios	Completar `razaoSocial`, `endereco`, etc.
`CNAE_INCOMPATIVEL`	CNAE não relacionado ao item LC 116 informado	Conferir cadastro do prestador

Autorização

Código	Significado	Como resolver
`LOGIN_PREFEITURA`	Credenciais do contribuinte inválidas no município	Atualizar no portal cliente
`CADASTRO_INATIVO`	CNPJ baixado ou suspenso	Regularizar com a prefeitura
`SEM_AUTORIZACAO_EMISSAO`	Contribuinte não habilitado pra emissão eletrônica	Solicitar liberação no portal correspondente
`CERTIFICADO_INVALIDO`	Cert A1 expirado, revogado ou CNPJ não bate	Renovar cert no portal cliente
`SERIE_RPS_NAO_AUTORIZADA`	Série RPS divergente da autorizada pelo município	Configurar série correta na empresa

Sequência (auto-tratado)

Código	Significado	Ação
`RPS_FORA_SEQUENCIA`	Número RPS divergente do esperado pelo provedor	Notare ressincroniza counter automaticamente
`RPS_JA_USADO`	Número RPS já consumido em emissão anterior	Notare avança o counter
`RPS_CANCELADO`	Número RPS marcado como cancelado	Notare avança o counter

Infraestrutura (transitório)

Código	Significado
`TIMEOUT`	Provedor não respondeu em tempo
`UPSTREAM_5XX`	Erro do servidor da prefeitura
`CIRCUIT_BREAKER_OPEN`	Notare cortou requests pra esse município por instabilidade — retenta automaticamente
`CONNECTION_REFUSED`	TCP recusado pelo provedor
`WAF_BLOCK`	Firewall bloqueou — Notare ajusta padrão de retry

Todos têm retry automático com backoff exponencial (15s → 30s → 60s → 120s → 240s → 480s).

Adapter (Notare interno)

Código	Significado
`XSD_VIOLATION`	XML gerado não bate com schema do provedor — bug ou XSD mudou
`SIGNATURE_FAIL`	Assinatura XMLDSig inválida
`NAMESPACE_ERROR`	Namespace XML errado no envelope
`FIELD_ORDER`	Ordem de elementos no XML viola sequência esperada

Esses sinalizam algo a investigar do nosso lado. Abra um ticket com o id da NFS-e que a gente acompanha.

Erros de transporte (antes de chegar na prefeitura)

Código	Categoria	Significado
`SEM_CERTIFICADO_A1`	cliente	Empresa sem cert ativo cadastrado
`CERTIFICADO_EXPIRADO`	cliente	Cert vencido
`SEM_CREDENCIAIS_PROVEDOR`	cliente	Login/senha do provedor ausente quando exigido
`CIRCUIT_BREAKER_OPEN`	infraestrutura	Notare bloqueou temporariamente — aguarde
`CONNECTION_TIMEOUT`	infraestrutura	TCP timeout

Acompanhar saúde no admin

Operadores Notare têm dashboard de saúde: Admin → Saúde de adapters. Mostra:

Taxa de cada categoria por período (24h / 7d / 30d)
Alerta quando adapter > 2% (provável bug ou mudança no provedor)
Códigos novos aparecendo (sinal de XSD mudou)

Não substitui ticket, mas dá visibilidade pré-suporte.

Formato do erro​

Validação de schema (HTTP 400)​

Rejeição da NFS-e (no body do response do POST /v1/nfse)​

Categorias​

Códigos por categoria​

Cliente (mais comuns)​

Autorização​

Sequência (auto-tratado)​

Infraestrutura (transitório)​

Adapter (Notare interno)​

Erros de transporte (antes de chegar na prefeitura)​

Acompanhar saúde no admin​