Erros da API - NZOChain

O filtro HTTP devolve JSON com success: false e, quando existe, um code em SCREAMING_SNAKE.

Auth

HTTP	Quando
401	`X-API-Key` ausente, inválida ou revogada

Plano e quotas (v1)

HTTP	`code`	Quando
403	`SCOPE_REQUIRED`	A key não tem o scope exigido (ex. `wallet.scan`). Corpo pode incluir `required`.
403	`PLAN_UPGRADE_REQUIRED`	Feature (Firewall analyze/simulate ou threats) acima do plano. Corpo inclui `feature` e `upgradeUrl`.
403	`SIMULATION_QUOTA`	Quota mensal de `simulate` esgotada. Corpo inclui `used` e `quota`.

Exemplo:

{
  "success": false,
  "statusCode": 403,
  "code": "PLAN_UPGRADE_REQUIRED",
  "message": "This API v1 feature requires a higher B2B plan.",
  "upgradeUrl": "/pricing"
}

Volume de API calls

Plano	Comportamento
Free	Hard cap. Ao ultrapassar a quota mensal → `429 RATE_LIMIT` (`limit`, `used`, `resetAt`). Sem overage pago.
Starter / Growth / Business	Overage faturado até 3× a quota (pedido continua). Acima do teto → `429 HARD_CEILING` (`limit`, `used`, `resetAt`, `upgradeUrl`).
Enterprise	Custom / ilimitado sob contrato (pilot-grade).

Não digas que “calls extra nunca bloqueiam” — isso era incorrecto para Free e para o teto 3× dos planos pagos.

Outros

HTTP	Uso típico
400	Body inválido (morada, network, calldata)
429	Também rate limit de infra / per-key (além das quotas mensais acima)
500	Falha interna; mensagem ao cliente é genérica em produção

Stats públicos (GET /api/stats/public) não exigem API key.