Rate limits

# On every successful response (2xx):
RateLimit-Policy: "tenant";q=2500;w=60
RateLimit: "tenant";r=2310;t=37
 
# On a 429 (rate limit exceeded):
RateLimit-Policy: "tenant";q=2500;w=60
RateLimit: "tenant";r=0;t=37
Retry-After: 37

# On every successful response, read remaining headroom:
remaining = parse(RateLimit, "r")         # remaining requests this window
quota     = parse(RateLimit-Policy, "q")  # total quota this window
window    = parse(RateLimit, "t")         # seconds until window resets
 
# Proactive throttle, to slow down before hitting the ceiling.
# Guard remaining > 0: it is legitimately 0 on the last permitted 200,
# and dividing by it gives Infinity (or a ZeroDivisionError in Python).
if remaining > 0 and remaining < 0.20 * quota:
  sleep(window / remaining)   # spread the remaining budget over the window
elif remaining == 0:
  sleep(window)               # no budget left, wait out the window
 
# On 429, read the CODE first. BUDGET_EXHAUSTED is an account-safety ceiling,
# not a rate limit: no wait clears it, so surface it instead of sleeping.
if err.code == "BUDGET_EXHAUSTED":
  raise SafetyCeiling(err.row, err.reset_at, err.hint.parameter)
 
# Otherwise back off exponentially and add jitter to avoid a thundering herd.
# Take whichever is longer: the server's Retry-After, or your own backoff.
wait  = max(Retry-After, delay) + random(0, 2)
sleep(wait)
delay = min(60, delay * 2)
 
# Give up after a bounded number of attempts rather than looping forever.
# example delay sequence: 2, 4, 8, 16, 32, 60, 60, ...

// TypeScript: proactive throttle + bounded on-429 backoff
const API_KEY = process.env.CURVIATE_API_KEY ?? "cvt_live_<your_key>";
const BASE = "https://api.curviate.com";
const MAX_ATTEMPTS = 6;
 
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
 
function parseStructuredField(header: string, key: string): number {
  const match = header.match(new RegExp(`${key}=(\\d+)`));
  return match ? parseInt(match[1]!, 10) : 0;
}
 
async function apiRequest(path: string, body?: unknown): Promise<unknown> {
  let delay = 2; // backoff seconds, doubled on each 429
 
  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
    const res = await fetch(`${BASE}${path}`, {
      method: body ? "POST" : "GET",
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        "Content-Type": "application/json",
      },
      body: body ? JSON.stringify(body) : undefined,
    });
 
    // Proactive throttle on successful responses
    if (res.ok) {
      const policy = res.headers.get("RateLimit-Policy") ?? "";
      const usage  = res.headers.get("RateLimit") ?? "";
      const quota     = parseStructuredField(policy, "q");
      const remaining = parseStructuredField(usage,  "r");
      const windowSec = parseStructuredField(usage,  "t");
 
      // remaining is legitimately 0 on the last permitted 200. Dividing by it
      // yields Infinity, which silently disables throttling instead of applying it.
      if (quota > 0 && windowSec > 0 && remaining < 0.20 * quota) {
        const waitSec = remaining > 0 ? windowSec / remaining : windowSec;
        await sleep(waitSec * 1000);
      }
      return res.json();
    }
 
    // Handle 429: RATE_LIMIT_ACCOUNT, RATE_LIMIT_TENANT, or PLATFORM_RATE_LIMIT.
    // BUDGET_EXHAUSTED also arrives as a 429 and must NOT be retried: it is an
    // account-safety ceiling, no wait clears it, and its reset can be weeks out.
    if (res.status === 429) {
      const err = await res.clone().json() as { code: string; row?: string; reset_at?: string | null };
      if (err.code === "BUDGET_EXHAUSTED") {
        throw new Error(`Safety ceiling on ${err.row}; frees at ${err.reset_at ?? "no fixed time"}.`);
      }
      const retryAfter = parseInt(res.headers.get("Retry-After") ?? "60", 10);
      const jitter = Math.random() * 2;
      // Honour whichever is longer: the server's hint, or our own backoff.
      await sleep((Math.max(retryAfter, delay) + jitter) * 1000);
      delay = Math.min(60, delay * 2);
      continue;
    }
 
    // Other errors
    const err = await res.json() as { code: string; message: string };
    throw new Error(`${err.code}: ${err.message}`);
  }
 
  throw new Error(`Still rate limited after ${MAX_ATTEMPTS} attempts.`);
}
 
// Usage
const accounts = await apiRequest("/v1/accounts");

# Python: proactive throttle + bounded on-429 backoff using httpx
import os, re, time, random
import httpx
 
API_KEY = os.environ.get("CURVIATE_API_KEY", "cvt_live_<your_key>")
BASE = "https://api.curviate.com"
MAX_ATTEMPTS = 6
 
def parse_sf(header: str, key: str) -> int:
    m = re.search(rf"{key}=(\d+)", header)
    return int(m.group(1)) if m else 0
 
def api_request(path: str, body: dict | None = None):
    delay = 2  # backoff seconds, doubled on each 429
 
    for _ in range(MAX_ATTEMPTS):
        method = "POST" if body else "GET"
        res = httpx.request(
            method,
            f"{BASE}{path}",
            headers={"Authorization": f"Bearer {API_KEY}"},
            json=body,
        )
 
        if res.is_success:
            policy  = res.headers.get("ratelimit-policy", "")
            usage   = res.headers.get("ratelimit", "")
            quota     = parse_sf(policy, "q")
            remaining = parse_sf(usage, "r")
            window    = parse_sf(usage, "t")
 
            # remaining is legitimately 0 on the last permitted 200, and
            # window / 0 raises ZeroDivisionError. Wait out the window instead.
            if quota > 0 and window > 0 and remaining < 0.20 * quota:
                time.sleep(window / remaining if remaining > 0 else window)
 
            return res.json()
 
        if res.status_code == 429:
            # BUDGET_EXHAUSTED shares the 429 and must NOT be retried: it is an
            # account-safety ceiling, no wait clears it, and its reset can be
            # weeks out.
            # NOT `body`: that name is this function's request payload, and
            # rebinding it here would make the next attempt POST the error.
            err = res.json()
            if err.get("code") == "BUDGET_EXHAUSTED":
                raise Exception(
                    f"Safety ceiling on {err.get('row')}; "
                    f"frees at {err.get('reset_at') or 'no fixed time'}."
                )
            retry_after = int(res.headers.get("retry-after", "60"))
            jitter = random.uniform(0, 2)
            # Honour whichever is longer: the server's hint, or our own backoff.
            time.sleep(max(retry_after, delay) + jitter)
            delay = min(60, delay * 2)
            continue
 
        err = res.json()
        raise Exception(f"{err['code']}: {err['message']}")
 
    raise Exception(f"Still rate limited after {MAX_ATTEMPTS} attempts.")
 
# Usage
accounts = api_request("/v1/accounts")

requests per 60 s  = 2500 + 1000 x seats
requests per 10 s  =  600 +  250 x seats