Erros

A API segue convenções REST. Erros retornam sempre um objeto JSON com o campoerrore opcionalmente message,campos eerrorCode.

Formato de Erro

{
  "error": "Créditos esgotados",
  "errorCode": "CREDIT_LIMIT",
  "creditsUsed": 500,
  "creditsLimit": 500,
  "upgradeUrl": "/settings/billing"
}

Status	Nome	Descrição
400	Bad Request	Payload inválido. O campo campos no body detalha quais campos falharam.
401	Unauthorized	Header x-api-key ausente ou formato inválido.
403	Forbidden	Chave revogada, sem assinatura ativa, ou créditos esgotados.
404	Not Found	Recurso não encontrado (invoice, batch, endpoint).
422	Unprocessable	Configuração incompleta: certificado ausente, município não configurado, etc.
429	Too Many Requests	Rate limit excedido. Aguarde o tempo indicado em Retry-After (segundos).
500	Internal Server Error	Erro inesperado no servidor. Tente novamente em alguns instantes.

Esses códigos aparecem no campo errorCode de invoices ou de respostas de erro.

Código	Descrição
CREDIT_LIMIT	Limite de notas mensais atingido. Necessário upgrade de plano.
E0039	Município não aderente ao sistema SNNFSE federal. Verifique configuração.
CERT_EXPIRED	Certificado A1 expirado. Faça o upload de um novo certificado.
CERT_MISSING	Nenhum certificado A1 válido encontrado para o projeto.
SP_1057	Erro de validação SP: RPS com numeração duplicada.
SP_1001	Erro de validação SP: CNPJ do prestador inválido.
SP_306	Erro de validação SP: código de serviço não encontrado.
RNG6110	Erro de validação SNNFSE: campo obrigatório ausente no DPS.
E0532	Tributação ISSQN inválida para o serviço informado. Para serviços do Item 99 da LC 116 (ex: "990101" — sem incidência de ISSQN/ICMS), informe valores.aliquotaIss: 0.

429

Aguarde Retry-After segundos, depois reenvie a requisição.

403 CREDIT_LIMIT

Apresente ao usuário um prompt de upgrade. Não reenvie.

422

Corrija a configuração no dashboard (certificado, município, CCM). Não reenvie.

500

Reenvie com backoff exponencial (3s, 9s, 27s). Após 3 tentativas, alerte manualmente.