API Rate Limits & Request Quotas

Understand how CloudNexus enforces rate limits, how to monitor your quota usage, and best practices for handling throttling in production systems.

Rate Limit Headers

Every CloudNexus API response includes rate limit headers to help you track quota consumption. These are included in both successful and error responses.

Plan-Based Limits

Rate limits scale based on your subscription tier. Enterprise customers can request custom limits through their dedicated support engineer.

Handling 429 Too Many Requests

When you exceed your quota, the API returns a 429 status code with a structured JSON body. Always respect the Retry-After header.

{
  "error": "rate_limit_exceeded",
  "message": "You have exceeded your allowed request quota for this window.",
  "retry_after": 24,
  "documentation_url": "https://docs.cloudnexus.com/api/v1/rate-limits/requests",
  "quota_reset_at": "2025-12-01T14:35:00Z"
}

Implementation Examples

Implement exponential backoff with jitter to gracefully handle throttling without overwhelming the API during recovery.

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await fetch(url, options);
    
    if (res.status === 429) {
      const retryAfter = parseInt(res.headers.get('retry-after') || '', 10) || Math.pow(2, attempt) * 1000;
      console.warn(`Rate limited. Retrying in ${retryAfter}ms`);
      await new Promise(r => setTimeout(r, retryAfter));
      continue;
    }
    
    return res.json();
  }
  throw new Error('Max retries exceeded due to rate limiting');
}

import time
import requests

def cloudnexus_request(endpoint, retries=3):
    for i in range(retries):
        res = requests.get(endpoint)
        if res.status_code == 429:
            wait = float(res.headers.get('retry-after', 2**i))
            print(f"Rate limited. Waiting {wait}s...")
            time.sleep(wait)
            continue
        return res.json()
    raise Exception("Exceeded retry limit")

Best Practices

• Cache aggressively: Use ETag and Last-Modified headers to avoid redundant fetches.
• Batch operations: Use the /batch endpoint when creating or updating multiple resources simultaneously.
• Idempotency keys: Include Idempotency-Key in request headers for safe retries on network failures.
• Monitor headers: Log X-RateLimit-Remaining to track usage trends and scale proactively.
• Webhooks over polling: Use event-driven webhooks instead of frequent API polling for real-time updates.