Rate Limits

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

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.

Rate Limit Headers

Every API response includes rate limit headers:

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:

{
  "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/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:

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

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")

Best Practices

Check remaining quota before bursting

Read X-RateLimit-Remaining from each response. If you’re approaching zero, throttle proactively instead of hitting the wall.

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.

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.

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.

Need higher limits? Contact us at support@nearnode.io or upgrade to Enterprise for custom rate limits tailored to your workload.

Getting Started

Core Features

Developer Console

Enterprise Governance

Limits by Plan

Rate Limit Headers

Handling `429 Too Many Requests`

Recommended Retry Strategy

Best Practices

​Limits by Plan

​Rate Limit Headers

​Handling 429 Too Many Requests

​Recommended Retry Strategy

​Best Practices

Limits by Plan

Rate Limit Headers

Handling `429 Too Many Requests`

Recommended Retry Strategy

Best Practices