Rate Limits & Errors

Rate Limits

The StackFlow API enforces rate limits at two layers: API Gateway throttling (account-wide) and per-user application-level limits.

Throttle Headers

Every API response includes rate limit headers so you can proactively manage your quota:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1716134460
X-RateLimit-Window: 60
Retry-After: 23  # Only present on 429 responses

HTTP Status Codes

Error Response Format

All error responses follow this consistent structure:

{
  "error": "Human-readable error message",
  "code": "MACHINE_READABLE_ERROR_CODE",
  "requestId": "7f3a1c2d-8e9b-4f0a-b1c2-d3e4f5a6b7c8",
  "details": {
    "field": "priority",
    "issue": "must be one of P1, P2, P3, P4"
  }
}

The requestId maps directly to the CloudWatch Logs request ID for the Lambda invocation. Include it when opening a support ticket.

Error Code Reference

Retry Strategies

Implement exponential backoff with jitter for robust API integrations:

import time
import random
import requests

def api_call_with_retry(url, headers, method="GET", body=None, max_retries=5):
    retryable_codes = {429, 500, 503}
    for attempt in range(max_retries):
        try:
            resp = requests.request(method, url, headers=headers, json=body, timeout=30)
            if resp.status_code not in retryable_codes:
                return resp
            if resp.status_code == 429:
                retry_after = int(resp.headers.get("Retry-After", 60))
                time.sleep(retry_after)
                continue
            # Exponential backoff with jitter
            wait = (2 ** attempt) + random.uniform(0, 1)
            time.sleep(min(wait, 60))
        except requests.exceptions.Timeout:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)
    return resp