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 per client IP using fixed-window counters in Redis.

Defaults (may change)

Production asset GET /v1/assets/:mint exposes X-RateLimit-Limit: 60 from the **per-route** counter (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, /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

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.

Error catalog

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.