Rate limits

// limiter.mjs: spaces calls out using the RateLimit-* headers. Node 22+.
const BASE = process.env.FILMO_BASE_URL ?? "https://app.filmo.io";
const AVAILABILITY = ["/api/v1/availability/check", "/api/v1/staff/availability", "/api/v1/vehicles/availability"];

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

class Bucket {
  remaining = Infinity; // from RateLimit-Remaining
  resetAt = 0; // when the window resets, from RateLimit-Reset
  tail = Promise.resolve(); // one request at a time per bucket

  async wait() {
    const pause = this.resetAt - Date.now();
    if (this.remaining <= 0 && pause > 0) await sleep(pause);
  }

  update(headers) {
    const remaining = Number(headers.get("ratelimit-remaining"));
    const reset = Number(headers.get("ratelimit-reset"));
    if (!headers.has("ratelimit-remaining") || Number.isNaN(remaining) || Number.isNaN(reset)) return;
    this.remaining = remaining;
    this.resetAt = Date.now() + reset * 1000;
  }
}

// The key has 120/min for everything. The three availability checks also count against
// their own 30/min quota, so they consume both buckets.
const buckets = { global: new Bucket(), availability: new Bucket() };

export function filmoCall(method, path, body) {
  const isAvailability = AVAILABILITY.includes(path);
  const used = isAvailability ? [buckets.global, buckets.availability] : [buckets.global];
  const bucket = buckets.global;
  const run = Promise.all(used.map((b) => b.tail)).then(async () => {
    for (let attempt = 0; ; attempt++) {
      for (const b of used) await b.wait();
      const res = await fetch(BASE + path, {
        method,
        headers: {
          Authorization: `Bearer ${process.env.FILMO_API_KEY}`,
          ...(body ? { "Content-Type": "application/json" } : {}),
        },
        body: body ? JSON.stringify(body) : undefined,
      });
      // The headers describe the tighter quota. For an availability check that is
      // usually its own; the global bucket just counts the call it consumed.
      if (isAvailability) {
        buckets.availability.update(res.headers);
        buckets.global.remaining -= 1;
      } else {
        bucket.update(res.headers);
      }
      if (res.status !== 429 || attempt >= 5) return res;
      // Over the limit: wait for Retry-After (seconds), then try the same call again.
      await sleep((Number(res.headers.get("retry-after")) || 1) * 1000);
    }
  });
  for (const b of used) b.tail = run.then(() => {}, () => {});
  return run;
}

// Example: 300 reads in a row never trigger a 429.
for (let i = 0; i < 300; i++) {
  const res = await filmoCall("GET", "/api/v1/orders?limit=1");
  if (!res.ok) throw new Error(String(res.status));
}

# limiter.py: spaces calls out using the RateLimit-* headers. Python 3 with requests.
import os
import threading
import time
from contextlib import ExitStack

import requests

BASE = os.environ.get("FILMO_BASE_URL", "https://app.filmo.io")
AVAILABILITY = {"/api/v1/availability/check", "/api/v1/staff/availability", "/api/v1/vehicles/availability"}


class Bucket:
    def __init__(self):
        self.remaining = float("inf")  # from RateLimit-Remaining
        self.reset_at = 0.0  # when the window resets, from RateLimit-Reset
        self.lock = threading.Lock()  # one request at a time per bucket

    def wait(self):
        pause = self.reset_at - time.time()
        if self.remaining <= 0 and pause > 0:
            time.sleep(pause)

    def update(self, headers):
        try:
            self.remaining = int(headers["RateLimit-Remaining"])
            self.reset_at = time.time() + int(headers["RateLimit-Reset"])
        except (KeyError, ValueError):
            pass


# The key has 120/min for everything. The three availability checks also count against
# their own 30/min quota, so they consume both buckets.
BUCKETS = {"global": Bucket(), "availability": Bucket()}


def filmo_call(method, path, body=None):
    is_availability = path.split("?")[0] in AVAILABILITY
    used = [BUCKETS["global"], BUCKETS["availability"]] if is_availability else [BUCKETS["global"]]
    with ExitStack() as stack:
        for b in used:
            stack.enter_context(b.lock)
        for attempt in range(6):
            for b in used:
                b.wait()
            res = requests.request(
                method,
                BASE + path,
                json=body,
                headers={"Authorization": f"Bearer {os.environ['FILMO_API_KEY']}"},
                timeout=30,
            )
            # The headers describe the tighter quota. For an availability check that is
            # usually its own; the global bucket just counts the call it consumed.
            if is_availability:
                BUCKETS["availability"].update(res.headers)
                BUCKETS["global"].remaining -= 1
            else:
                BUCKETS["global"].update(res.headers)
            if res.status_code != 429 or attempt == 5:
                return res
            # Over the limit: wait for Retry-After (seconds), then try the same call again.
            time.sleep(float(res.headers.get("Retry-After") or 1))


# Example: 300 reads in a row never trigger a 429.
for _ in range(300):
    filmo_call("GET", "/api/v1/orders?limit=1").raise_for_status()