API Rate Limiting

The IronWiFi REST API enforces rate limits to ensure fair usage and platform stability. This guide explains the limits, how to handle rate-limited responses, pagination for large data sets, and best practices for efficient API usage.

Rate Limits

Default limits

Limit	Value
Requests per minute	100 per API key
Burst allowance	Up to 20 requests in a 1-second burst
Concurrent connections	10 per API key

Rate limits are applied per API key, not per IP address. If you have multiple API keys, each has its own independent limit.

Rate limit headers

Every API response includes headers that show your current rate limit status:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1705312800

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

When you hit the limit

If you exceed the rate limit, the API returns a

429 Too Many Requests

response:

{
  "error": true,
  "message": "Rate limit exceeded. Try again in 45 seconds.",
  "code": 429
}

The response includes a

Retry-After

header:

Retry-After: 45

Always respect the

Retry-After

header. Continuing to send requests while rate-limited may result in longer cooldown periods.

Pagination

Large collections (users, sessions, vouchers) are paginated. Use pagination parameters to retrieve data in manageable chunks instead of requesting everything at once.

Pagination parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number (1-based)
`per_page`	integer	50	Results per page (max 100)

Example: Paginated user list

# First page (50 users)
curl -X GET "https://console.ironwifi.com/api/users?page=1&per_page=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Second page
curl -X GET "https://console.ironwifi.com/api/users?page=2&per_page=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Pagination response metadata

Paginated responses include metadata about the total result set:

{
  "data": [
    {"id": 1, "username": "user1"},
    {"id": 2, "username": "user2"}
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 237,
    "total_pages": 5
  }
}

Iterating through all pages

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://console.ironwifi.com/api"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def get_all_users():
    """Retrieve all users across all pages."""
    all_users = []
    page = 1
    per_page = 100  # Maximum per page

    while True:
        response = requests.get(
            f"{BASE_URL}/users",
            headers=HEADERS,
            params={"page": page, "per_page": per_page}
        )
        response.raise_for_status()
        result = response.json()

        users = result.get("data", result)
        all_users.extend(users)

        pagination = result.get("pagination", {})
        if page >= pagination.get("total_pages", 1):
            break

        page += 1

    return all_users

tip

Always use the maximum

per_page

value (100) when retrieving large data sets. This reduces the total number of API calls and helps you stay within rate limits.

Quotas

In addition to per-minute rate limits, certain operations have daily or monthly quotas:

Operation	Quota	Period
User creation	Depends on plan	Monthly
Voucher generation	Depends on plan	Monthly
Report exports	Depends on plan	Daily
Webhook deliveries	Depends on plan	Monthly

Quota information is available in the IronWiFi Console under Account > Usage.

Handling Rate Limits

Exponential backoff

Implement exponential backoff to handle rate-limited responses gracefully:

import requests
import time

def api_request_with_backoff(method, url, headers,
                              json=None, max_retries=5):
    """Make an API request with exponential backoff on rate limiting."""
    for attempt in range(max_retries + 1):
        response = requests.request(
            method, url, headers=headers, json=json
        )

        if response.status_code != 429:
            return response

        # Get retry delay from header, or calculate with backoff
        retry_after = int(
            response.headers.get("Retry-After", 2 ** attempt)
        )
        print(f"Rate limited. Retrying in {retry_after} seconds "
              f"(attempt {attempt + 1}/{max_retries})")
        time.sleep(retry_after)

    return response

Pre-check remaining quota

Before starting a batch operation, check your remaining rate limit:

def check_rate_limit(headers):
    """Check current rate limit status."""
    response = requests.get(
        f"{BASE_URL}/users?per_page=1",
        headers=headers
    )
    remaining = int(
        response.headers.get("X-RateLimit-Remaining", 0)
    )
    reset_time = int(
        response.headers.get("X-RateLimit-Reset", 0)
    )
    return remaining, reset_time

Batch operations

When you need to create or update many resources, pace your requests to stay within limits:

import time

def batch_create_users(users, headers):
    """Create multiple users with rate limit awareness."""
    results = []
    request_count = 0

    for user in users:
        # Pause every 80 requests to stay safely under the limit
        if request_count > 0 and request_count % 80 == 0:
            print("Approaching rate limit, pausing for 60 seconds...")
            time.sleep(60)

        response = requests.post(
            f"{BASE_URL}/users",
            headers=headers,
            json=user
        )

        if response.status_code == 429:
            retry_after = int(
                response.headers.get("Retry-After", 60)
            )
            print(f"Rate limited, waiting {retry_after} seconds...")
            time.sleep(retry_after)
            # Retry the same request
            response = requests.post(
                f"{BASE_URL}/users",
                headers=headers,
                json=user
            )

        results.append({
            "username": user["username"],
            "status": response.status_code,
            "response": response.json()
        })
        request_count += 1

    return results

Best Practices

1. Cache responses locally

Do not fetch the same data repeatedly. Cache API responses and refresh only when needed:

import time

class IronWiFiCache:
    def __init__(self, ttl_seconds=300):
        self.cache = {}
        self.ttl = ttl_seconds

    def get(self, key):
        if key in self.cache:
            data, timestamp = self.cache[key]
            if time.time() - timestamp < self.ttl:
                return data
        return None

    def set(self, key, data):
        self.cache[key] = (data, time.time())

cache = IronWiFiCache(ttl_seconds=300)  # 5-minute cache

def get_users(headers):
    cached = cache.get("users")
    if cached:
        return cached

    response = requests.get(
        f"{BASE_URL}/users",
        headers=headers
    )
    users = response.json()
    cache.set("users", users)
    return users

2. Use webhooks instead of polling

Instead of polling the API for changes, use webhooks to receive real-time notifications. This eliminates unnecessary API calls entirely.

Approach	API Calls per Day	Latency
Poll every minute	1,440	Up to 60 seconds
Poll every 5 minutes	288	Up to 5 minutes
Webhooks	0 (only event-driven)	Real-time (seconds)

3. Minimize payload size

Request only the data you need:

Use pagination with appropriate
```
per_page
```
values
Apply filters (date range, username, status) to narrow results
Avoid fetching full collections when you only need a single resource

4. Use bulk operations

When available, prefer bulk endpoints over individual resource calls:

# Instead of creating 100 vouchers one at a time (100 API calls):
# Use the batch generation endpoint (1 API call):
curl -X POST "https://console.ironwifi.com/api/vouchers/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"quantity": 100, "validity": 86400}'

5. Implement circuit breakers

If the API returns repeated errors, back off instead of hammering it:

class CircuitBreaker:
    def __init__(self, failure_threshold=5, reset_timeout=120):
        self.failures = 0
        self.threshold = failure_threshold
        self.reset_timeout = reset_timeout
        self.last_failure_time = 0
        self.is_open = False

    def record_failure(self):
        self.failures += 1
        self.last_failure_time = time.time()
        if self.failures >= self.threshold:
            self.is_open = True

    def record_success(self):
        self.failures = 0
        self.is_open = False

    def can_proceed(self):
        if not self.is_open:
            return True
        # Allow retry after reset timeout
        if time.time() - self.last_failure_time > self.reset_timeout:
            self.is_open = False
            return True
        return False

6. Handle errors gracefully

Do not retry on 4xx errors (except 429). They indicate a problem with your request, not a transient issue:

Status Code	Should Retry?	Action
400	No	Fix the request payload
401	No	Fix authentication
403	No	Check permissions
404	No	Fix the resource ID or URL
429	Yes	Wait and retry with backoff
500	Yes	Retry with backoff
502	Yes	Retry with backoff
503	Yes	Retry with backoff

See Error Codes for the complete error reference.

Requesting Higher Limits

If your integration requires higher rate limits:

Review your current usage to confirm you are using the API efficiently
Implement caching, webhooks, and batch operations to reduce request volume
Contact IronWiFi support at support@ironwifi.com with:
- Your current API usage patterns
- The rate limit you need
- Your use case justification

REST API -- API overview and base URLs
API Authentication -- API key management
API Endpoints -- Complete endpoint reference
Error Codes -- API error reference
Webhooks -- Real-time event notifications (alternative to polling)

Was this page helpful?

Rate Limits​

Default limits​

Rate limit headers​

When you hit the limit​

Pagination​

Pagination parameters​

Example: Paginated user list​

Pagination response metadata​

Iterating through all pages​

Quotas​

Handling Rate Limits​

Exponential backoff​

Pre-check remaining quota​

Batch operations​

Best Practices​

1. Cache responses locally​

2. Use webhooks instead of polling​

3. Minimize payload size​

4. Use bulk operations​

5. Implement circuit breakers​

6. Handle errors gracefully​

Requesting Higher Limits​

Related Topics​