Usage Tracking & Quotas

Acceso meters usage at the infrastructure layer. Metering is associated with API keys. It is aggregated into quota windows for enforcement and billing.

• Flat: every accepted request costs 1.

• Weighted: expensive routes cost N units.

• Hybrid: weight by endpoint category and response size.

Common models:

The default unit is “request cost”. Not all endpoints need to cost the same.

What counts as “usage”

Rate limits control short bursts. Quotas control long-window totals. You usually want both.

Quota windows

Quotas can be enforced on:

• Daily windows (good for abuse containment).

• Monthly windows (good for billing plans).

• Custom windows (enterprise contracts).

Quota burn is usually concurrency-driven. Cap parallel requests per key.

Control concurrency

Cache stable metadata (token symbol/decimals). Cache historical lookups. Revalidate only when needed.

Cache aggressively on the client

Use pagination and filters. Avoid N+1 account fan-outs when possible.

Prefer coarse queries over many small queries

Practical patterns to reduce quota pressure

If you need strict semantics, treat them as contract-level. Do not infer from one-off observations.

• 401 / 403 are rejected early and do not count.

• 429 responses do not count.

• Successful requests count.

• Some deployments count 5xx only if domain work started.

Counting rules are policy-driven. A common default:

What gets billed / counted

Example: reading quota headers with curl

curl -sS -D - \
  -H "Authorization: Bearer $ACCESO_API_KEY" \
  "https://<YOUR_ACCESO_API_HOST>/v1/solana/account/<ADDRESS>" \
  -o /dev/null

• RateLimit-Limit: allowed units for the current window.

• RateLimit-Remaining: remaining units in the window.

• RateLimit-Reset: seconds until the window resets.

Common fields:

Responses can include headers that describe current usage state. Use them to self-throttle without guesswork.

Usage headers (client feedback loop)

Example: 429 quota error payload

{
  "success": false,
  "error": {
    "code": "quota_exceeded",
    "message": "Quota exceeded for this API key.",
    "details": {
      "window": "monthly",
      "unit": "request_cost"
    }
  },
  "meta": {
    "request_id": "req_b12c9e",
    "timestamp": 1765939200
  }
}

• quota_exceeded

Typical error code:

Quota-exceeded requests return 429. They fail fast at the gateway.

Enforcement behavior

Windows are evaluated per API key. One key cannot spend another key’s quota.

If your workload is inherently high-frequency, polling will hurt. Prefer streaming, webhooks, or push-based patterns where available.

Example: adaptive concurrency (pseudocode)

remaining = header("RateLimit-Remaining")
if remaining < 10:
  concurrency = 1
else if remaining < 100:
  concurrency = 5
else:
  concurrency = 20