Rate Limiting

To ensure fair usage and maintain server performance, the Manifold API enforces rate limits on all endpoints. If you exceed the allowed number of requests within a specified time frame, you’ll receive a 429 Too Many Requests response. Below is an explanation of how the rate-limiting system works and best practices for managing your API calls efficiently.

Rate Limit Overview

The Manifold API enforces rate limits on a per-token basis to ensure fairness and availability for all users. The limits apply to both the number of requests per minute and burst requests.

Rate Limit Parameters

Rate limits are communicated via headers in the API response:

Rate Limit Response

If you exceed the rate limit, the API will respond with a 429 Too Many Requests status code and the following response body:

{
  "status": 429,
  "message": "Rate limit exceeded. Too many requests.",
  "retryAfter": 15
}

• retryAfter: Indicates the number of seconds you should wait before retrying the request.

Best Practices for Handling Rate Limits

To avoid hitting rate limits and ensure uninterrupted API access, follow these best practices:

1. Monitor Rate Limit Headers

• Track the X-RateLimit-Remaining and X-RateLimit-Reset headers to monitor your API usage.
• Plan your requests to avoid exceeding limits, particularly during high-demand periods.

2. Implement Exponential Backoff

When a 429 error occurs:

• Use the retryAfter value from the response to determine the appropriate wait time.
• Gradually increase retry intervals using exponential backoff for repeated 429 errors.

Example:

import time

def make_request_with_backoff():
    retries = 0
    max_retries = 5
    while retries < max_retries:
        response = make_api_request()  # Replace with your API call

        if response.status_code == 429:  # Rate limited
            retry_after = int(response.json().get("retryAfter", 1))
            time.sleep(retry_after)
            retries += 1
        else:
            return response

    raise Exception("Max retries exceeded. Please try again later.")

3. Batch Requests

• Use pagination to retrieve large datasets with the limit and cursor parameters.
• Combine multiple queries into fewer API calls wherever possible.

4. Cache Frequently Accessed Data

• Store results from frequently accessed endpoints (e.g., /drivers or /vehicles) to reduce duplicate requests.

5. Optimize Workflows

• Prioritize essential API calls over redundant ones.
• Avoid polling endpoints too frequently. Use event-driven updates where applicable.

Retry Strategy

When encountering a 429 Too Many Requests error, follow this retry strategy:

1. Pause the Request:
   • Use the retryAfter value in the response to determine how long to wait before retrying.
2. Retry After Delay:
   • Gradually increase retry intervals using exponential backoff.
3. Limit Retry Attempts:
   • To avoid infinite retry loops, set a maximum retry count.

Example Workflow

1. Monitor Headers:
   • Track the X-RateLimit-Remaining value in each response.
2. Implement Backoff:
   • Use exponential backoff to handle 429 responses.
3. Optimize Requests:
   • Batch data retrieval and cache frequently accessed data.

Example Response with Rate Limit Headers

{
  "status": 200,
  "message": "Success",
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "John Doe",
      "email": "[email protected]"
    }
  ],
  "headers": {
    "X-RateLimit-Limit": 100,
    "X-RateLimit-Remaining": 95,
    "X-RateLimit-Reset": 1700000000
  }
}

By following these guidelines and implementing the suggested strategies, you can efficiently manage your API usage within the Manifold platform’s rate limits while ensuring uninterrupted service.