Pagination and Rate Limits

All mCards list endpoints return paginated responses. The platform also enforces per-partner rate limits to ensure fair usage across all integrations.

Pagination

Query Parameters

If per_page exceeds the maximum, it is capped at 40. If omitted, the default is 20.

Response Structure

All paginated responses include a pagination object alongside the resource data:

{
  "cardholders": [ ... ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "count": 20,
    "total_count": 143
  }
}

Iterating Through Pages

To retrieve all results, increment the page parameter until count is less than per_page or the current page reaches ceil(total_count / per_page).

page = 1
all_results = []

while True:
    response = make_request("GET", f"/api/distributors/v1/cardholders?page={page}&per_page=40")
    all_results.extend(response["cardholders"])

    pagination = response["pagination"]
    if pagination["count"] < pagination["per_page"]:
        break
    page += 1

Sorting

Many list endpoints support sorting via sort and sort_direction query parameters:

GET /api/distributors/v1/cardholders?sort=created_at&sort_direction=desc&page=1&per_page=20

Available sort fields vary by endpoint — see the API Reference for endpoint-specific options.

Rate Limits

mCards enforces per-partner rate limits using a sliding window algorithm. Limits are tracked independently for each partner and reset continuously (no fixed boundary resets).

Rate Limit Tiers

Your tier is assigned during partner onboarding. Contact your mCards partner manager to discuss tier upgrades.

How Limits Are Applied

• Read and write limits are tracked independently — consuming your read quota does not affect your write quota
• Limits are per partner account (identified by your API key), not per IP address
• Each partner's counters are independent — one partner hitting their limit does not affect others

Rate Limit Response

When you exceed your rate limit, the API returns a 429 Too Many Requests response:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 12

{
  "errors": [
    {
      "status": "429",
      "detail": "Rate limit exceeded. Retry after 12 seconds."
    }
  ]
}

The Retry-After header indicates the number of seconds to wait before retrying. This value is calculated based on when the oldest request in your current window will expire.

Handling Rate Limits

Implement exponential backoff or respect the Retry-After header:

import time

def make_request_with_retry(method, path, body=None, max_retries=3):
    for attempt in range(max_retries):
        response = make_request(method, path, body)

        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 60))
            time.sleep(retry_after)
            continue

        return response

    raise Exception("Rate limit exceeded after max retries")

Best Practices

1. Cache responses — Avoid repeated identical requests by caching list results locally
2. Use pagination efficiently — Request the maximum per_page (40) to reduce the number of requests needed
3. Spread requests over time — Distribute API calls evenly rather than bursting
4. Monitor for 429s — Log rate limit responses and adjust your request patterns accordingly
5. Use webhooks for real-time data — Instead of polling for changes, subscribe to webhook events

Related Guides

• API Authentication and Credentials — How to authenticate API requests
• Error Handling and Reliability — Handling errors and retries
• Webhooks API Concepts — Real-time event notifications (alternative to polling)