Erros

Todos os erros retornam JSON no formato padrão com o campo request_id para rastreabilidade.

Formato do erro

{
  "error":      "VALIDATION_ERROR",     // código de erro
  "message":    "campos inválidos",     // mensagem em português
  "fields": [                           // apenas em VALIDATION_ERROR
    { "field": "tomador.documento", "message": "CNPJ deve ter 14 dígitos" }
  ],
  "request_id": "uuid"                  // para suporte
}

Códigos da API

INVALID_API_KEYHTTP 401

API Key ausente, malformada ou revogada.

Como resolver: Verifique o header Authorization: Bearer sk_live_<chave>. Confirme que a chave não foi revogada no dashboard.

PLAN_LIMIT_REACHEDHTTP 402

Limite de emissões do plano atual atingido para o mês corrente.

Como resolver: Faça upgrade do plano em GET /v1/billing/portal ou aguarde a renovação mensal.

FORBIDDENHTTP 403

A API Key não tem permissão para acessar o recurso (ex.: nota de outro MEI).

Como resolver: Cada MEI só acessa suas próprias notas. Verifique se está usando a chave correta.

NOT_FOUNDHTTP 404

Recurso não encontrado.

Como resolver: Confirme o ID da nota. Notas de outros MEIs retornam 404 (não 403) por isolamento.

ALREADY_CANCELLEDHTTP 409

Tentativa de cancelar uma nota que já foi cancelada.

Como resolver: Verifique o status atual com GET /v1/nfse/:id antes de cancelar.

VALIDATION_ERRORHTTP 422

Campos obrigatórios ausentes ou com formato inválido.

Como resolver: Verifique o campo "fields" no payload de erro — ele lista cada campo problemático.

RECEITA_REJECTIONHTTP 422

A Receita Federal rejeitou a NFS-e. O corpo traz nota_id, status "REJEITADA", erro_codigo e erro_descricao.

Como resolver: Corrija os dados conforme erro_descricao e reenvie com uma NOVA Idempotency-Key (a antiga devolve a nota rejeitada).

INVALID_NBSHTTP 422

Código NBS inválido ou não encontrado.

Como resolver: Confira o código em servico.codigo_nbs na tabela NBS da Receita.

CERTIFICADO_AUSENTEHTTP 422

A empresa emissora ainda não enviou o certificado A1.

Como resolver: Faça o upload do certificado (.pfx) no painel em Configurações → Certificado A1.

INSCRICAO_MUNICIPAL_OBRIGATORIAHTTP 422

ME/EPP sem Inscrição Municipal cadastrada — a Receita rejeitaria a nota.

Como resolver: Cadastre a Inscrição Municipal no painel em Configurações → Dados.

MUNICIPIO_NAO_HABILITADOHTTP 422

O município da empresa emissora ainda não aderiu à NFS-e Nacional.

Como resolver: Consulte a lista de municípios ativos em gov.br/nfse.

IDEMPOTENCY_KEY_CONFLICTHTTP 409

A Idempotency-Key enviada já está em uso por outra requisição.

Como resolver: Use uma chave única por nota (ex.: o ID do pedido no seu sistema ou um UUID).

INTERNAL_ERRORHTTP 500

Erro inesperado no servidor.

Como resolver: Aguarde e tente novamente. Se persistir, abra um issue com o request_id retornado.

Erros da Receita Federal

Quando a Receita rejeita uma NFS-e, o campo erro_codigo no webhook (e em GET /v1/nfse/:id) contém o código abaixo. Lista completa em docs/receita-erros.md.

Código	Descrição
`E001`	CNPJ do prestador não habilitado para NFS-e Nacional
`E002`	Certificado digital inválido ou expirado
`E010`	CNPJ do tomador inválido ou não encontrado
`E011`	CPF do tomador inválido
`E020`	Código NBS inválido ou não autorizado para o prestador
`E021`	Discriminação do serviço muito curta (mínimo 10 caracteres)
`E030`	Valor do serviço menor que o mínimo permitido
`E031`	Alíquota ISS fora do intervalo permitido pelo município
`E040`	Competência inválida ou fora do período permitido
`E055`	Número RPS duplicado para este prestador
`E077`	Nota já cancelada — não é possível cancelar novamente
`E099`	Erro interno da Receita Federal — tente novamente