X API rate limit 429: what triggers it and how to back off

const MAX_ATTEMPTS = 5;

async function callX(req: Request) {
  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
    const res = await fetch(req);
    if (res.status !== 429) return res; // 403 and 400 are terminal, hand them back

    const waitMs = waitFromHeaders(res.headers) ?? backoffWithJitter(attempt);
    if (waitMs > 15 * 60_000) throw new Error('daily cap hit, resume at reset');
    await sleep(waitMs);
  }
  throw new Error('rate limited after ' + MAX_ATTEMPTS + ' attempts');
}

function waitFromHeaders(h: Headers): number | null {
  // The daily write cap wins: its reset can be hours out.
  const daily = h.get('x-user-limit-24hour-remaining');
  const key = daily === '0' ? 'x-user-limit-24hour-reset' : 'x-rate-limit-reset';
  const reset = h.get(key);
  if (!reset) return null;
  return Math.max(0, Number(reset) * 1000 - Date.now()) + 1_000; // epoch seconds, not a delay
}

function backoffWithJitter(attempt: number): number {
  const base = Math.min(60_000, 1_000 * 2 ** attempt);
  return base / 2 + Math.random() * (base / 2);
}

# On 429, OpenTweet returns Retry-After in plain seconds.
curl -i -X POST https://opentweet.io/api/v1/posts \
  -H "Authorization: Bearer ot_your_key" \
  -H "Content-Type: application/json" \
  -d '{"text":"Queued from a worker.","publish_now":true}'

# X-RateLimit-Limit: 60
# X-RateLimit-Remaining: 59
# X-RateLimit-Reset: 1756636800