Pular para o conteúdo
Docs

Erros, códigos e rejeições da Sefin

Atualizado em

Nesta página

Há dois tipos de erro na API: os erros da requisição, devolvidos na hora com um código HTTP 4xx/5xx, e as rejeições da Sefin, que chegam depois, no status da nota. Trate os dois.

Envelope de erro#

Toda resposta de erro tem o mesmo formato:

Erro
{
  "status": "error",
  "message": "Dados inválidos",
  "code": "VALIDATION_ERROR",
  "details": [
    { "campo": "servico.valor", "mensagem": "Use string decimal, ex.: \"1500.00\"" }
  ]
}
Campo Descrição
status Sempre "error"
message Texto em português para pessoas. Pode mudar sem aviso
code Identificador estável. É por ele que o seu código decide
details Informação estruturada, quando houver. Pode vir null

Códigos HTTP#

HTTP Significado Repetir?
200 / 201 Sucesso —
202 Aceito para processamento (emissão, substituição, cancelamento) —
400 Requisição malformada (ex.: falta Idempotency-Key) Não, corrija
401 Chave ausente, inválida, expirada ou revogada Não
403 Sem escopo, cota esgotada ou assinatura bloqueada Não
404 Recurso não existe ou é de outra empresa Não
409 Conflito de estado (ex.: cancelar nota já cancelada) Não
422 Dados inválidos ou chave de idempotência reusada Não, corrija
429 Rate limit. Respeite Retry-After Sim, depois da espera
5xx Falha da Emitra Sim, com a mesma Idempotency-Key

Catálogo de code#

code HTTP Quando acontece O que fazer
UNAUTHORIZED 401 Chave ausente ou inválida Confira o header e a chave
FORBIDDEN 403 A chave não tem o escopo da rota Crie uma chave com o escopo
NOT_FOUND 404 Id inexistente ou de outra empresa Confira o id e o ambiente da chave
VALIDATION_ERROR 422 Corpo ou parâmetro inválido Veja details e corrija
CONFLICT 409 Registro duplicado (ex.: tomador com o mesmo documento) Use o registro existente
IDEMPOTENCY_KEY_REUSED 422 Mesma Idempotency-Key com corpo diferente Gere outra chave para outra operação
COTA_EXCEDIDA 403 Acabou a cota de notas do plano Troque de plano ou aguarde o próximo mês
TENANT_INADIMPLENTE 403 Assinatura em atraso além da carência Regularize a fatura no painel
CERTIFICADO_VENCIDO 403 Certificado A1 ausente, vencido ou inválido Envie um A1 válido
FISCAL_DPS_INVALID 422 A DPS violou uma regra conhecida antes do envio Corrija os campos apontados
FISCAL_INVALID_TRANSITION 409 A operação não vale para o status atual da nota Consulte o status antes
RATE_LIMITED 429 Muitas chamadas no minuto Espere Retry-After segundos

Exemplo de bloqueio por cota:

403 COTA_EXCEDIDA
{
  "status": "error",
  "message": "A cota de notas do plano acabou neste mês",
  "code": "COTA_EXCEDIDA",
  "details": null
}

Rejeições da Sefin#

Uma rejeição não é erro da requisição: o POST /nfse já respondeu 202. Ela aparece quando a nota muda para status: "rejected", no GET /nfse/{id} e no webhook nfse.rejected:

Nota rejeitada (trecho)
{
  "id": "3c9b7e1a-6d42-4f8e-a0b3-7e2f5d1c9a84",
  "status": "rejected",
  "rejeicao": {
    "codigo": "E0116",
    "mensagem_oficial": "Inscrição municipal do prestador obrigatória.",
    "titulo": "Inscrição municipal obrigatória",
    "orientacao": "O município exige a inscrição municipal do prestador. Preencha a IM no perfil fiscal.",
    "tipo": "municipality",
    "campo": "IM"
  }
}
Campo Descrição
codigo Código oficial da Sefin (Anexo I do leiaute)
mensagem_oficial Texto devolvido pela Sefin, sem alteração
titulo, orientacao Explicação da Emitra em português, com a correção
tipo Categoria da rejeição (tabela abaixo)
campo Campo da DPS relacionado, quando conhecido

Tipos de rejeição#

tipo Significa Ação típica
business Dado da nota incoerente com as regras Corrigir e emitir de novo, com nova Idempotency-Key
municipality Depende da parametrização ou do convênio do município Ajustar a configuração fiscal ou o serviço
certificate Problema com o certificado A1 Enviar outro certificado
schema XML fora do leiaute. Normalmente é falha nossa Abrir chamado no suporte
duplicate DPS já usada. A Emitra recupera a nota existente Nenhuma: não é erro
technical Erro sem catálogo ou de transporte Tentar de novo ou abrir chamado

Mapa das rejeições mais comuns#

Código Título Como corrigir
E0006 Ambiente divergente A nota foi para um ambiente diferente do configurado. Revise o ambiente da empresa
E0008 Data de emissão no futuro Diferença de relógio. A Emitra tenta de novo em instantes
E0010 Série fora da faixa permitida Para sistema próprio, a série vai de 1 a 49999
E0014 DPS já utilizada Não é erro: a Emitra recupera a nota já emitida
E0015 Competência posterior à emissão A competência não pode ser futura
E0037 Município sem convênio O município não usa o emissor nacional; emita pelo sistema da prefeitura
E0050 Prazo de substituição expirado Avalie o cancelamento por análise fiscal
E0116 Inscrição municipal obrigatória Preencha a IM no perfil fiscal
E0120 Inscrição municipal não deve ser informada Remova a IM do perfil fiscal
E0160 Opção pelo Simples divergente O regime não confere com a Receita na competência. Revise o regime
E0204 Tomador sem CNPJ/CPF com ISS retido Para reter o ISS, identifique o tomador
E0237 Tomador sem endereço com ISS retido Informe o endereço nacional do tomador
E0428 Descontos e retenções maiores que o serviço Reduza descontos ou retenções
E0429 Carga de ISS abaixo de 2% Deduções ou benefícios não podem levar o ISS abaixo de 2%
E0583 MEI não pode ter ISS retido Para MEI, marque ISS não retido
E0595 Alíquota acima de 5% A alíquota do ISS não passa de 5%
E0617 Alíquota não deve ser informada Município conveniado: a Sefin aplica a alíquota parametrizada
E0619 Alíquota obrigatória O município de incidência não está ativo; informe a alíquota
E0655 Retenção não parametrizada no município O município não prevê retenção neste caso; marque ISS não retido
E0718 Assinado com certificado de outro CNPJ Use o A1 do próprio prestador
E0822 Prazo de cancelamento expirado Peça o cancelamento extemporâneo (análise fiscal)
E0823 Valor acima do permitido para cancelamento Use a análise fiscal
E0855 IBS/CBS obrigatório Informe CST, classificação e cIndOp do IBS/CBS no cadastro do serviço
E1000 Erro da Calculadora IBS/CBS Revise CST/cClassTrib do serviço
E1203 Certificado vencido Envie um certificado A1 dentro da validade
E1235 XML fora do leiaute oficial Se persistir, abra chamado (pode ser mudança de leiaute)

Para códigos fora desta lista, a Emitra devolve a mensagem_oficial da Sefin com tipo: "business" (ou technical, para códigos E12xx). O catálogo completo, com as cerca de 575 regras do Anexo I, é a base da explicação no painel.

Status error não é rejeição#

status: "error" indica falha técnica (rede, indisponibilidade da Sefin). A Emitra tenta de novo sozinha, com espera crescente, e consulta a Sefin pelo Id da DPS antes de cada reenvio. Você não precisa reenviar a nota.

Próximos passos#

Esta página foi útil?