Rate Limits

Nexus enforces a monthly request quota and a per-second rate limit on every API key. Both depend on your plan. The limits below apply identically to the Blockfrost-compatible surface (/api/v0). It is the same key on the same plan, so its traffic counts against the same monthly quota and the same per-second limit as native traffic. There is no separate compatibility allowance.

Limits by plan

Plan	Requests / mo	Rate limit	Burst	API keys
Starter	3M	10 req/s	100	2
Builder	10M	25 req/s	250	4
Growth	30M	50 req/s	500	7
Scale	50M	100 req/s	1,000	13
Enterprise	200M	500 req/s	5,000	Unlimited

Burst is the token-bucket depth: the maximum number of requests you can fire in an instant before the per-second rate limit throttles you.

Starter covers the core API only. Add-ons, bundles and WebSocket packages are available on Builder, Growth and Scale, and Enterprise includes all of them. REST add-ons draw on the same monthly quota as the core API.

Without an active subscription

Nexus has no free tier. Requests authenticated against an expired, cancelled-and-lapsed, or suspended subscription, and any request that can’t be tied to an active plan, are refused with HTTP 402 subscription_required (see Add-on gating).

Rate limit headers

Metered responses carry three headers describing your monthly quota:

Header	Meaning
`X-RateLimit-Limit`	Your plan’s monthly request quota
`X-RateLimit-Remaining`	Requests left this month (never below 0)
`X-RateLimit-Reset`	When the quota refills, as Unix epoch seconds - 00:00 UTC on the 1st of next month

X-RateLimit-Limit: 10000000
X-RateLimit-Remaining: 9857201
X-RateLimit-Reset: 1782864000

These headers describe the monthly quota only. The per-second rate limit is not reported in headers - on a per-second 429, read Retry-After instead (see below).

Scope and absence:

The headers appear on metered REST responses - the blockchain data endpoints that count against your quota. Dashboard and account-management endpoints (auth, billing, /api/user, /api/keys) are not metered and don’t carry them.
They are not sent for MCP traffic (/mcp/** reports quota errors inside the JSON-RPC envelope) or on WebSocket streams.
Plans with an unlimited request allowance (Enterprise arrangements without a monthly cap) get no X-RateLimit-* headers at all. Absence is not an error - it just means no monthly cap applies.

When you hit a limit

Nexus returns HTTP 429 with a JSON body. There are two cases, and you can tell them apart by their headers: Monthly quota exhausted - the response carries the X-RateLimit-* headers (X-RateLimit-Remaining: 0), a Retry-After header with the seconds until your quota refills, and reset_at in the body (the same instant as X-RateLimit-Reset, as an ISO timestamp):

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 10000000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1782864000
Retry-After: 1728000

{
  "error": "rate_limit_exceeded",
  "message": "Monthly request limit reached. Upgrade at https://nexus.gerowallet.io/dashboard/billing/",
  "limit": 10000000,
  "reset_at": "2026-07-01T00:00:00Z"
}

Per-second rate exceeded - no X-RateLimit-* headers, just Retry-After: 1. Slow down and retry shortly:

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded — slow down",
  "limit": 25
}

Branch on header presence: a 429 with X-RateLimit-Reset (or reset_at in the body) means your monthly quota is exhausted until the reset - don’t retry in a loop. A 429 with only Retry-After: 1 means you’re sending too fast right now.

On /api/v0 the 429 body is Blockfrost’s, not the shape above. The limits are the same; only the envelope differs. It uses Blockfrost’s status_code / error / message fields, with error set to Project Over Limit, and it still sends Retry-After, so a Blockfrost SDK’s built-in backoff works unchanged. See Blockfrost compatibility.

Counters reset at 00:00 UTC on the 1st of each month. The reset job runs at - or moments after - that instant, so a request fired exactly at the boundary can still see one final 429. Tolerate a single extra retry right at reset time rather than treating it as an error.

Add-on gating (402)

Endpoints behind a paid add-on (Market Data, Wallet Analytics, Transaction Builder, IPFS) return HTTP 402 when the add-on isn’t active on your plan, either on its own or through a bundle that covers it:

{
  "error": "payment_required",
  "addon": "marketData",
  "message": "Upgrade required at https://nexus.gerowallet.io/dashboard/billing/"
}

An account with no active subscription at all gets a 402 with a different error and no addon:

{
  "error": "subscription_required",
  "message": "An active subscription is required. Subscribe at https://nexus.gerowallet.io/dashboard/billing/"
}

Handling 429s

Read Retry-After first - both 429 variants send it:

async function fetchWithBackoff(url, options, maxRetries = 4) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, options);
    if (response.status !== 429) return response;

    // Monthly quota: don't hammer - surface to the caller.
    const body = await response.clone().json().catch(() => ({}));
    if (response.headers.get('X-RateLimit-Reset') || body.reset_at) {
      throw new Error(`Monthly quota reached, resets ${body.reset_at}`);
    }

    // Per-second: honor Retry-After, fall back to exponential backoff.
    const retryAfter = Number(response.headers.get('Retry-After'));
    const waitSeconds = retryAfter > 0 ? retryAfter : Math.pow(2, attempt);
    await new Promise((r) => setTimeout(r, waitSeconds * 1000));
  }
  throw new Error('Rate limited after retries');
}

Best practices

Cache responses

Cache frequently accessed, slow-changing data (block / tx / asset metadata) to cut request volume against your monthly quota.

Spread bursts

Keep sustained throughput under your tier’s per-second limit; the burst bucket absorbs short spikes, not steady overload.

Monitor usage

Watch X-RateLimit-Remaining on your responses so you can adjust before hitting the monthly cap.

Upgrading

Need higher limits? Contact nexus@gerowallet.io.

Next steps

Error Handling

How Nexus reports API errors

Pagination

Working with paginated responses

Getting Started

Migrations

Core Concepts

Add-ons & Streaming

API Reference

Limits by plan

Without an active subscription

Rate limit headers

When you hit a limit

Add-on gating (402)

Handling 429s

Best practices

Upgrading

Next steps

Error Handling

Pagination

​Limits by plan

​Without an active subscription

​Rate limit headers

​When you hit a limit

​Add-on gating (402)

​Handling 429s

​Best practices

​Upgrading

​Next steps

Error Handling

Pagination

Limits by plan

Without an active subscription

Rate limit headers

When you hit a limit

Add-on gating (402)

Handling 429s

Best practices

Upgrading

Next steps