Rate limits and quotas

import os
import random
import time

import requests

BASE_URL = "https://api.surfais.com/v1"
API_KEY = os.environ["SURFAIS_API_KEY"]
MAX_ATTEMPTS = 5
MAX_WAIT_SECONDS = 120


class RetryLater(Exception):
    """The API asked for a wait too long to sleep through, such as a spent monthly quota."""

    def __init__(self, code, retry_after, request_id):
        super().__init__(f"{code}: retry in {retry_after} s (request {request_id})")
        self.code = code
        self.retry_after = retry_after
        self.request_id = request_id


def request_with_backoff(method, path, **kwargs):
    """Send one request. On 429 or 503, wait and try again, up to MAX_ATTEMPTS times."""
    headers = {"Authorization": f"Bearer {API_KEY}", **kwargs.pop("headers", {})}
    for attempt in range(MAX_ATTEMPTS):
        response = requests.request(
            method, f"{BASE_URL}{path}", headers=headers, timeout=30, **kwargs
        )
        if response.status_code not in (429, 503) or attempt == MAX_ATTEMPTS - 1:
            return response

        retry_after = response.headers.get("Retry-After")
        if retry_after is None:
            # No header: exponential backoff with full jitter.
            wait = random.uniform(0, min(MAX_WAIT_SECONDS, 2**attempt))
        else:
            wait = int(retry_after)
            if wait > MAX_WAIT_SECONDS:
                body = response.json()
                raise RetryLater(body["error"]["code"], wait, body["request_id"])
            # Many clients are released at the same instant. Spread them out a little.
            wait += random.uniform(0, 1)
        time.sleep(wait)


if __name__ == "__main__":
    response = request_with_backoff("GET", "/orgs")
    response.raise_for_status()
    print("Requests left this minute:", response.headers.get("X-RateLimit-Remaining"))
    for org in response.json()["data"]:
        print(org["id"], org["name"])

// Node 18+. Save as backoff.mjs and run: node backoff.mjs
const BASE_URL = "https://api.surfais.com/v1";
const API_KEY = process.env.SURFAIS_API_KEY;
const MAX_ATTEMPTS = 5;
const MAX_WAIT_SECONDS = 120;

const sleep = (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1000));

// The API asked for a wait too long to sleep through, such as a spent monthly quota.
class RetryLater extends Error {
  constructor(code, retryAfter, requestId) {
    super(`${code}: retry in ${retryAfter} s (request ${requestId})`);
    this.code = code;
    this.retryAfter = retryAfter;
    this.requestId = requestId;
  }
}

// Send one request. On 429 or 503, wait and try again, up to MAX_ATTEMPTS times.
async function requestWithBackoff(method, path, options = {}) {
  const headers = { Authorization: `Bearer ${API_KEY}`, ...options.headers };
  for (let attempt = 0; ; attempt++) {
    const response = await fetch(`${BASE_URL}${path}`, { ...options, method, headers });
    const retryable = response.status === 429 || response.status === 503;
    if (!retryable || attempt === MAX_ATTEMPTS - 1) return response;

    const retryAfter = response.headers.get("Retry-After");
    let wait;
    if (retryAfter === null) {
      // No header: exponential backoff with full jitter.
      wait = Math.random() * Math.min(MAX_WAIT_SECONDS, 2 ** attempt);
    } else {
      wait = Number(retryAfter);
      if (wait > MAX_WAIT_SECONDS) {
        const body = await response.json();
        throw new RetryLater(body.error.code, wait, body.request_id);
      }
      // Many clients are released at the same instant. Spread them out a little.
      wait += Math.random();
    }
    await sleep(wait);
  }
}

const response = await requestWithBackoff("GET", "/orgs");
if (!response.ok) throw new Error(`Request failed with ${response.status}`);
console.log("Requests left this minute:", response.headers.get("X-RateLimit-Remaining"));
for (const org of (await response.json()).data) {
  console.log(org.id, org.name);
}