Rate limits protect the Data Mammoth API infrastructure and ensure fair access for all users. This guide explains how rate limits work, how to monitor your usage, and best practices for building efficient API integrations.

Rate Limit Overview

API requests are limited based on your account type and authentication method:

Rate Limit Headers

Every API response includes headers that communicate your rate limit status:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1710684000

What Happens When You Hit the Limit

If you exceed the rate limit, the API returns:

HTTP/1.1 429 Too Many Requests

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Please retry after 30 seconds.",
    "status": 429,
    "retry_after": 30
  }
}

The retry_after value indicates how many seconds to wait before making another request.

Best Practices

1. Implement Exponential Backoff

When you receive a 429 response, wait and retry with increasing delays:

import time
import requests
def api_request_with_retry(url, headers, max_retries=5):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code == 429:
            wait_time = int(response.headers.get('Retry-After', 2 ** attempt))
            time.sleep(wait_time)
            continue
        return response
    raise Exception("Max retries exceeded")

2. Cache API Responses

Avoid unnecessary API calls by caching data that does not change frequently:

• Server list — Cache for 30 to 60 seconds.
• Plan/region lists — Cache for hours or days (these rarely change).
• Account details — Cache for minutes.
• Metrics — Cache based on the polling interval you need.

3. Use Webhooks Instead of Polling

Instead of repeatedly calling the API to check for changes, set up webhooks to receive notifications when events occur. See Webhooks — Real-Time Event Notifications.

4. Use Pagination Efficiently

Request only the data you need:

# Instead of fetching all records
GET /v1/servers?per_page=100
Fetch smaller pages
GET /v1/servers?per_page=25&page=1

See API Pagination & Filtering.

5. Batch Related Operations

Group related API calls together instead of making individual calls:

• Fetch a server list once and filter locally, rather than making separate calls for each server.
• Use query parameters to filter results server-side.

6. Monitor Your Rate Limit Usage

Check the rate limit headers in every response:

response = requests.get(url, headers=headers)
remaining = int(response.headers.get('X-RateLimit-Remaining', 0))
if remaining < 10:
    print(f"Warning: Only {remaining} requests remaining")

7. Spread Requests Over Time

If you need to make many requests, spread them evenly across the rate limit window rather than sending them all at once.

8. Use Conditional Requests

Where supported, use If-Modified-Since or ETag headers to avoid downloading unchanged data:

curl -X GET "https://api.datamammoth.com/v1/servers" \
  -H "Authorization: Bearer dm_key_abc123def456" \
  -H "If-None-Match: \"etag_value\""

If the data has not changed, the API returns 304 Not Modified without consuming body bandwidth.

Requesting Higher Limits

If your use case requires higher rate limits:

Enterprise customers can negotiate custom rate limits as part of their service agreement.

What to Do Next

• API Error Codes & Handling — Handle all error types.
• API Pagination & Filtering — Efficient data retrieval.
• Webhooks — Replace polling with push notifications.
• API Overview — Full API reference.