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"
}HTTP Status Codes
| 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. |
| 402 | Payment Required | Recurso ou limite de Produção exige upgrade de plano (ex.: múltiplos CNPJs em Produção ou domínio White-Label). |
| 403 | Forbidden | Chave revogada, sem assinatura ativa, créditos esgotados ou limite de Sandbox atingido. |
| 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. |
Códigos de Aplicação
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. |
| PAYWALL_PRODUCTION_PROJECT_REQUIRED | Limite de projetos ativos em Produção (ambiente=1) do plano atingido. Necessário upgrade para Developer ou SaaS Pro. |
| PAYWALL_WHITELABEL_REQUIRED | Configuração de domínio White-Label (storageBaseUrl) exige plano SaaS Pro ou Enterprise. |
| SANDBOX_PROJECT_LIMIT_REACHED | Limite de projetos simultâneos em Homologação (ambiente=2) atingido (Free: 5, Dev: 10). |
| ORG_TOKEN_LIMIT_REACHED | Limite de Organization Tokens ativos atingido para o plano atual (Free/Dev: 3, SaaS Pro/Enterprise: 20). |
| 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. |
| E0312 | Código de tributação municipal (cTribMun / desdobro) inexistente ou com vigência encerrada para o serviço na data de competência informada. Remova o override de codigoTributacaoMunicipal ou utilize um desdobro vigente no município. |
| 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. |
| E0540 | Inconsistência de tributação ISSQN: o município de incidência não reconhece o serviço informado como tributável. Verifique a configuração de Tributação ISSQN nas Settings do projeto e se o código de serviço (cTribNac) está habilitado no município. |
| E0903 | Regra IBS/CBS (tpOper): valores.ibscbs.tipoOperacao ("1" a "5") é obrigatório em compras governamentais (tipoEnteGovernamental informado) ou quando servico.codigo pertencer exatamente aos subitens 100501, 100502, 150901, 171201 ou 250501; e vedado nos demais casos. Para tipoOperacao = 2 ou 3, informe também valores.ibscbs.chavesNfseReferenciadas (refNFSe). |
| E0932 | Regra IBS/CBS (imovel vs obra): valores.ibscbs.imovel (cib ou endereco completo) é obrigatório quando indicadorOperacao for "020101", "020201" ou "020301", exceto exclusivamente nos 11 códigos exatos de obra de construção civil (070201, 070202, 070401, 070501, 070502, 070601, 070602, 070701, 070801, 071701 e 071901, que utilizam servico.obra); e vedado nos demais casos. |
| E1235 | Falha no esquema XML do DF-e no SNNFSE (validação XSD da DPS/NFS-e, ex: transição do leiaute da Nota Técnica SE/CGNFS-e nº 009 v1.01). |
| CNPJ_ALFANUMERICO_NAO_SUPORTADO | CNPJ alfanumérico ([0-9A-Z]{12}\d{2}) ou chave DF-e alfanumérica enviado para um provedor municipal legado cujo schema XSD exige 14 dígitos estritamente numéricos (\d{14}). Na NFS-e, o CNPJ alfanumérico é suportado apenas no Ambiente Nacional (snnfse). |
Tratamento Recomendado
429Aguarde Retry-After segundos, depois reenvie a requisição.
403 CREDIT_LIMITApresente ao usuário um prompt de upgrade. Não reenvie.
422Corrija a configuração no dashboard (certificado, município, CCM). Não reenvie.
500Reenvie com backoff exponencial (3s, 9s, 27s). Após 3 tentativas, alerte manualmente.