Errors & rate limits

All API errors use a consistent JSON envelope:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message."
  }
}

Unexpected server errors may use a legacy Fastify shape without error.code. Client code should handle non-2xx responses defensively.

Stack traces are never returned to clients.

Rate limiting

When Upstash Redis is configured, public asset and collection routes are rate limited using fixed-window counters in Redis.

**Commercial Sprint C2** applies plan-based limits for keyed requests. See [developer-plans.md](./developer-plans.md) for the full matrix.

**C2.5 durable metering:** successful keyed requests on rate-limited public routes also increment daily Postgres counters (api_usage_daily) for portal and operator visibility. Metering is **fail-open** (a write failure never blocks the API). Monthly totals are **not** the same as RPM — they are attribution counters only, not billing.

Modes

Plan defaults (60s window)

Free keyed limits match anonymous IP limits. Builder and Pro raise RPM when a valid API key is presented.

Environment overrides

Production asset GET /v1/assets/:mint exposes X-RateLimit-Limit: 60 for anonymous/Free keyed traffic (the tighter of global + route limits is enforced).

Tiers

**Expensive** (global + per-route counters):

• GET /v1/assets/:mint (+ /health, /inspection, /media)
• POST /v1/assets/:mint/media/recover
• GET /v1/collections/:address (+ /assets, /health, /holders, /market)
• POST /v1/collections/:address/index

**Lightweight** (global counter only):

• GET /v1/assets/:mint/snapshot, /snapshots
• GET /v1/collections/:address/index
• GET /v1/collection-index-jobs/:jobId

Exempt:

• GET /health

**Not rate limited** (no matching rule):

• Monitor, event, and webhook routes

Response headers

429 envelope

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please retry after the window resets."
  }
}

Fail-open

If Redis errors during a rate limit check, the request is **allowed** and a warning is logged (RATE_LIMIT_CHECK_FAILED). Rate limiting is disabled entirely when Redis is not configured.

Client IP identity (anonymous only)

Rate limit keys hash the resolved client IP. X-Real-IP is honored **only** when the socket peer is in TRUST_PROXY_CIDRS (includes 100.0.0.0/8 on Railway). Untrusted peers ignore spoofed X-Real-IP. **X-Forwarded-For is not used** for rate-limit identity.

Keyed requests ignore IP for rate limiting — the API key ID is the bucket identifier.

Error catalog

Portal API key management (session BFF on owlviz.dev — not the public api.owlviz.dev surface):

CORS

When CORS_ALLOWED_ORIGINS is set, browser requests must originate from an allowed origin. Exposed headers include rate limit and cache headers listed above.