Chave, limites e extrato

GET/v1/account/usage

O extrato do mês em duas colunas: as chamadas que contam para o plano e as que não contam porque a falha foi nossa.

const uso = await nfse.account.usage();
console.log(uso.counted, "de", uso.account.monthly_limit, "· sobram", uso.remaining);

// aviso automático a partir de 80% do limite:
const comAviso = new Kalvi({
  onPlanUsage: (u) => console.warn(`${u.used}/${u.limit}, zera em ${u.resets}`),
});

r = requests.get(
    "https://api.kalvi.com.br/v1/account/usage",
    headers={"Authorization": f"Bearer {os.environ['KALVI_API_KEY']}"},
    timeout=20,
)
d = r.json()
print(d["counted"], "de", d["account"]["monthly_limit"], "| não cobradas:", d["not_charged"])

curl -s https://api.kalvi.com.br/v1/account/usage \
  -H "Authorization: Bearer $KALVI_API_KEY"

Resposta

Capturada da API, recortada para caber na tela.

{
  "api_version": "1",
  "tables_version": "2026-11-03",
  "account": { "email": "voce@escritorio.com.br", "plan": "free", "monthly_limit": 200 },
  "period": "2026-09",
  "resets_at": "2026-10-01",
  "counted": 6,
  "not_charged": 0,
  "remaining": 194,
  "by_route": [{ "route": "/v1/classify", "counted": 5, "not_charged": 0 }],
  "note": "Contabilizadas: chamadas que devolveram resultado ou erro de entrada. Não cobradas: falha nossa (5xx, timeout, indisponibilidade)."
}

O que saber antes de usar

• Só /v1/classify e /v1/validate consomem o plano. Ler o extrato, as tabelas ou o health é de graça.
• Conta para o limite a chamada que devolveu resultado (200) ou que foi recusada por entrada inválida (4xx).
• Falha nossa (5xx, timeout, indisponibilidade) **não** conta e aparece em not_charged.
• A partir de 80% toda resposta traz o cabeçalho X-Plan-Usage: used=; limit=; resets=.
• Em 100% as chamadas seguintes voltam 429 QUOTA_EXCEEDED com upgrade_url, resets_at e Retry-After.