Rate Limits

Understand API rate limits and how to handle them.

Limits

Response Headers

Every API response includes these headers:

Handling 429 Too Many Requests

When rate-limited, you receive a 429 response:

{
  "error": "Rate limit exceeded",
  "retryAfter": 42
}

Best Practices

• Implement exponential backoff when you receive a 429 response.
• Check X-RateLimit-Remaining to preemptively slow down requests.
• Batch operations where possible instead of making many individual requests.
• Cache responses to reduce redundant API calls.
• Use webhooks instead of polling to get delivery status.

Example: Retry with Backoff

import time, requests

def send_with_retry(payload, max_retries=3):
    for attempt in range(max_retries):
        r = requests.post(
            "https://api.notfs.dev/api/notifications",
            json=payload,
            headers={"X-API-Key": "ntfs_..."}
        )
        if r.status_code == 429:
            wait = r.json().get("retryAfter", 2 ** attempt)
            time.sleep(wait)
            continue
        r.raise_for_status()
        return r.json()
    raise Exception("Max retries exceeded")