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. Contém o código e descrição do erro da Receita.

Como resolver: Veja a tabela de erros da Receita em docs/receita-erros.md. Corrija os dados e reenvie.

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