Erros

Formato dos erros, códigos `ERROR_*` e códigos HTTP retornados pela API.

Campos não declarados nos DTOs são rejeitados, inclusive em objetos aninhados. Toda falha REST usa o mesmo corpo; não existe mais um campo error separado.

Formato do erro

json

{
  "statusCode": 400,
  "code": "ERROR_VALIDATION",
  "message": "Request validation failed",
  "details": [
    {
      "field": "customer.taxId",
      "code": "ERROR_INVALID_TAX_ID",
      "message": "Invalid tax ID"
    }
  ],
  "requestId": "9f1fc995-4ee4-4a92-b285-cf8dff227a97"
}

Decida pelo code e pelo status HTTP. message é sempre uma string em inglês (nunca um array) e serve para diagnóstico. details é opcional: em validação é um array de { field, code, message }; em erros de aplicação são objetos públicos tipados. requestId corresponde ao header X-Request-Id e pode ser informado ao suporte. Falhas 5xx usam mensagens sanitizadas, sem detalhes internos.

Erros em downloads de PDF/XML também seguem este contrato. Redirects, OAuth, MCP/JSON-RPC, health checks e respostas 204 mantêm seus formatos próprios.

Códigos HTTP

HTTP	Uso
200 / 201 / 202	Ação concluída / recurso criado / processamento assíncrono aceito.
204	Operação concluída sem corpo.
400	DTO, parâmetro, JSON, UUID, `limit` ou cursor inválido.
401 / 403	Autenticação ausente ou inválida / acesso negado (escopo, endpoint não habilitado para API key, empresa bloqueada).
404	Recurso inexistente, inclusive de outro tenant.
409 / 410	Conflito (CNPJ duplicado, idempotência conflitante, documentos ainda não prontos) / recurso encerrado.
413 / 415	Payload excessivo / codificação não suportada.
422	Validação fiscal no domínio ou regra de negócio rejeitada (prontidão, certificado, cota).
429	Rate limit ou cooldown; respeite `Retry-After`.
500 / 502 / 503 / 504	Erro interno / dependência inválida / indisponibilidade / timeout.

Códigos frequentes

code	Quando ocorre
`ERROR_VALIDATION`	Corpo ou query inválidos; veja `details[]`.
`ERROR_INVALID_LIMIT`	`limit` fora de 1–1000 ou não inteiro (400).
`ERROR_INVALID_CURSOR`	Cursor adulterado ou de outra coleção, tenant ou filtro (400).
`ERROR_RATE_LIMIT_EXCEEDED`	Limite de requisições excedido (429).
`ERROR_INSUFFICIENT_CREDITS` / `ERROR_QUOTA_EXCEEDED`	Créditos ou cota insuficientes para emitir.
`ERROR_COMPANY_NOT_READY` / `ERROR_COMPANY_BLOCKED`	Empresa sem certificado em `live`, ou bloqueada.
`ERROR_IDEMPOTENCY_CONFLICT`	Mesma `Idempotency-Key` com payload diferente (409).
`ERROR_TAX_REGIME_NOT_SUPPORTED`	Só empresas MEI e Simples Nacional são atendidas (422).
`ERROR_VALIDATION` com `details[].code` `ERROR_DEDUCTION_NOT_ALLOWED_FOR_REGIME` ou `ERROR_SIMPLES_SUBLIMIT_NOT_SUPPORTED`	Dedução da base do ISS que o MEI ou o Simples não pode declarar, ou Simples acima do sublimite (`regApTribSN` 2 ou 3), que ainda não é suportado (422).
`ERROR_GONE`	Operação encerrada, como a compra avulsa de créditos (410).

Boas práticas

Para respostas não 2xx, preserve status, code e requestId no diagnóstico, sem registrar a API key.
Faça retry com backoff para 429/503; em 429, aguarde o Retry-After. Na emissão, preserve a chave de idempotência e o payload.
Não repita erros de validação sem corrigir os dados indicados em details.