Two different 429s from one Express middleware, and how a client should tell them apart

[supertj]

If your API has paid plans, a 429 can mean two things. Either the caller is sending too fast, or they've used everything their plan includes for this billing period. A generic "retry on 429" helper treats both the same, and gets one of them badly wrong.

Here's the server side. The UsageRail middleware checks the caller's API key, then that customer's per-second and per-minute limits, then their quota, all before your route runs:

import express from "express";
import { usageRail } from "@usagerail/node/express";

const app = express();

// Registered before the middleware, so it's never checked or counted
app.get("/health", (req, res) => res.send("ok"));

app.use("/v1", usageRail({
  appKey: process.env.USAGERAIL_APP_KEY,
  auth: "api-key", // reads Authorization: Bearer <key>, or x-api-key
}));

app.get("/v1/reports/:reportId", (req, res) => {
  res.json({ id: req.params.reportId });
});

app.listen(3000);

When a customer goes over their rate limit:

HTTP/1.1 429 Too Many Requests
Retry-After: 1
RateLimit-Policy: "per_second";q=10;w=1, "per_minute";q=300;w=60
RateLimit: "per_second";r=0;t=1, "per_minute";r=212;t=18

{"error":"rate_limited","retry_after":1}

When they've used up the quota on a plan that stops at the limit:

HTTP/1.1 429 Too Many Requests
Retry-After: 1036800

{"error":"quota_exceeded","retry_after":1036800}

Same status code, but here Retry-After is the number of seconds left in the billing period, 12 days. A retry helper that sleeps on Retry-After parks the job for 12 days. One that ignores it and backs off exponentially keeps asking for something that won't come back until the period resets.

Checking the error field alone isn't quite enough either. quota_exceeded can also come back with Retry-After: 1 for a moment while the SDK is topping up its share of that customer's quota, and that one is worth retrying. What worked for me is to retry short waits and surface long ones:

async function callApi(url, key, attempts = 3) {
  for (let attempt = 1; attempt <= attempts; attempt++) {
    const res = await fetch(url, { headers: { Authorization: `Bearer ${key}` } });
    if (res.status !== 429) return res;

    const { error } = await res.json();
    const wait = Number(res.headers.get("retry-after") ?? "1");
    // A quota that ran out for the period comes back with a wait of days.
    // Don't sleep on that; let the caller decide what to do.
    if (wait > 60) {
      throw new Error(`${error}: retry after ${wait}s`);
    }
    await new Promise((resolve) => setTimeout(resolve, wait * 1000));
  }
  throw new Error("Still rate limited after retries");
}

A few Express-specific things I ran into:

• Order decides coverage. app.use(usageRail(...)) only covers routes registered after it. That's how /health above stays open, and it's also how a router mounted in an earlier file ends up silently unmetered.
• Route templates need the import first. Usage is grouped by template, such as /tenants/:tenantId/reports. Express doesn't keep a router's mount path as you wrote it, so the SDK records mount paths as routers are mounted. Import @usagerail/node/express before the modules that define your routers. Routers mounted earlier get grouped by the concrete path (/tenants/42/reports), so every tenant becomes its own row.
• A custom error body can drop the headers. If you replace the body with onReject, copy rejection.headers onto the response: res.status(rejection.status).set(rejection.headers).json(...). Without that, Retry-After and the RateLimit fields disappear and clients go back to guessing.
• Limits are per process by default. The token buckets live in each process's memory. With 4 processes and a limit of 10 per second, a customer whose requests spread evenly can get about 40 per second. There's a setting to split the limit across servers instead (10 / 4, rounded up, so 3 each), which keeps the total closer to 10 but holds back a customer whose requests all land on one process.
• Refused requests don't count as usage. Neither kind of 429 counts toward the customer's usage or quota, so a client stuck in a retry loop doesn't use up its own allowance. A rate_limited refusal also doesn't take a token from the bucket.

Disclosure: I work on UsageRail. The Express setup, options and the full list of rejection codes are at https://usagerail.com/docs/express