Rate Limits

X-RateLimit-Limit: 2000000
X-RateLimit-Remaining: 1857201
X-RateLimit-Reset: 1782864000

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 2000000
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": 2000000,
  "reset_at": "2026-07-01T00:00:00Z"
}

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

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

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

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');
}