Rate Limits and Retry Handling for Vendors

​

Rate limits

​

How rate limiting works

​

429 response contract

HTTP/1.1 429 Too Many Requests
Retry-After: 37

{"error": "Rate limit exceeded"}

​

Required client behavior

• You must wait the number of seconds specified in the Retry-After header before retrying.
• You must cache your JWT token for the full 6-hour lifetime and not call the token endpoint for every request.
• You should keep your sustained request rate at or below 15 requests per minute per location.
• You should iterate round-robin across locations when syncing data from multiple locations to spread load evenly.

​

Reference implementation (Python)

import time
import requests


def vendor_get(session, url, headers, max_attempts=3):
    for attempt in range(max_attempts):
        response = session.get(url, headers=headers)
        if response.status_code != 429:
            return response
        wait = int(response.headers.get("Retry-After", 60))
        time.sleep(wait + 1)
    raise RuntimeError("rate limited after %d attempts" % max_attempts)