> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nearnode.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate Limits

> Request quotas, rate limit headers, and best practices for high-volume integrations.

NearNode enforces rate limits to ensure platform stability across all tenants. Limits are applied per API key and vary by plan tier and operation type.

## Limits by Plan

| Plan       | Standard Requests | Batch Operations | Burst Allowance |
| ---------- | ----------------- | ---------------- | --------------- |
| Developer  | 100 req/min       | 10 req/min       | 20 req/s peak   |
| Pro        | 500 req/min       | 50 req/min       | 100 req/s peak  |
| Enterprise | Custom            | Custom           | Custom          |

<Info>
  **Ops Tip:** Standard requests include `GET`, `POST`, `PATCH`, and `DELETE` on nodes, analytics queries, and webhook management. Batch operations include `POST /batches` and batch generation endpoints.
</Info>

## Rate Limit Headers

Every API response includes rate limit headers:

```http theme={null}
HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1707494400
```

| Header                  | Description                                    |
| ----------------------- | ---------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed in the current window |
| `X-RateLimit-Remaining` | Requests remaining in the current window       |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets          |

## Handling `429 Too Many Requests`

When you exceed the limit, the API returns:

```json theme={null}
{
  "data": null,
  "error": "Rate limit exceeded. Retry after 12 seconds."
}
```

The response includes a `Retry-After` header with the number of seconds to wait:

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1707494412
```

## Recommended Retry Strategy

Implement exponential backoff with jitter:

<CodeGroup>
  ```javascript Node.js theme={null}
  async function fetchWithRetry(url, options, maxRetries = 3) {
    for (let attempt = 0; attempt <= maxRetries; attempt++) {
      const response = await fetch(url, options);

      if (response.status !== 429) return response;

      const retryAfter = parseInt(response.headers.get('Retry-After') || '1');
      const jitter = Math.random() * 1000;
      const delay = retryAfter * 1000 + jitter;

      console.log(`Rate limited. Retrying in ${Math.round(delay / 1000)}s...`);
      await new Promise(resolve => setTimeout(resolve, delay));
    }

    throw new Error('Max retries exceeded');
  }
  ```

  ```python Python theme={null}
  import time
  import random
  import requests

  def fetch_with_retry(url, headers, max_retries=3):
      for attempt in range(max_retries + 1):
          response = requests.get(url, headers=headers)

          if response.status_code != 429:
              return response

          retry_after = int(response.headers.get('Retry-After', 1))
          jitter = random.uniform(0, 1)
          delay = retry_after + jitter

          print(f"Rate limited. Retrying in {delay:.1f}s...")
          time.sleep(delay)

      raise Exception("Max retries exceeded")
  ```
</CodeGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Check remaining quota before bursting">
    Read `X-RateLimit-Remaining` from each response. If you're approaching zero, throttle proactively instead of hitting the wall.
  </Accordion>

  <Accordion title="Use bulk endpoints for batch operations">
    Creating 100 nodes individually burns 100 requests. Use `POST /batches` to generate them in a single call — it counts as one batch operation.
  </Accordion>

  <Accordion title="Cache read-heavy queries">
    If you're polling `GET /nodes` frequently, cache the response on your side and use webhooks to invalidate the cache when data changes.
  </Accordion>

  <Accordion title="Spread requests over time">
    If you need to update 200 nodes, spread the requests across 2+ minutes rather than firing them all at once. Your integration is more resilient and other tenants are unaffected.
  </Accordion>
</AccordionGroup>

<Tip>
  Need higher limits? Contact us at **[support@nearnode.io](mailto:support@nearnode.io)** or upgrade to Enterprise for custom rate limits tailored to your workload.
</Tip>