RateLimitError

What you'll see

A stitch with throttle: { delegate: true } that gets a rate-limit response (status in throttle.on, default [429]) rejects with a RateLimitError instead of retrying. It is a StitchError — a subclass — so it carries the usual status / attempts / body / url and is caught by a generic instanceof StitchError arm, while remaining its own exported class you can catch specifically to hand the signal to whatever owns your backoff:

import { RateLimitError, stitch } from 'stitchapi';

const fetchPage = stitch({
    baseUrl: 'https://api.example.com',
    path: '/pages/{id}',
    throttle: { delegate: true },
});

try {
    await fetchPage({ params: { id: '42' } });
} catch (e) {
    if (e instanceof RateLimitError) {
        console.log(e.status); // 429 (the rate-limit status that was hit)
        console.log(e.retryAfter); // ms parsed from Retry-After, or undefined
        console.log(e.response.headers); // the raw response, for other rate headers
    }
}

RateLimitError carries, on top of the inherited StitchError fields (status, attempts, body, url):

• retryAfter — the wait the server asked for, parsed from Retry-After (delta-seconds or an HTTP-date) into milliseconds; undefined when the header is absent or unparseable.
• response — the raw AdapterResult, so you can read other rate headers the API sent (X-RateLimit-Remaining, a reset timestamp, and so on).

Its status is the rate-limit status (e.g. 429, or whatever you listed in throttle.on) — always present, where the base class leaves it optional.

Why it happens

You opted into delegate-backoff because an outer gate or circuit — not StitchAPI — owns the rate budget. So when the API returns a rate-limit status, the stitch deliberately does not retry it and does not pace it on the internal throttle: it surfaces the outcome so your gate can apply the backoff, persist it, and decide when to release. This is the mode working as designed, not a new failure — the rate limit reached you on purpose.

How to handle it

• Feed it to your outer gate. Use retryAfter (falling back to your own default when it's undefined) to set the gate's penalty window, then let the gate gate the next attempt. That's the whole point of delegating.
• Read it off the stream instead. If you consume the event stream rather than awaiting, the same outcome arrives as an error event carrying status and retryAfter — no try/catch needed.
• Branch without throwing. .safe() returns the very same RateLimitError in error — SafeResult.error is typed StitchError, and this is one, so nothing is downgraded. instanceof RateLimitError, retryAfter, body and response all work identically whether you await or .safe().
• Reconsider whether to delegate. If nothing outside StitchAPI actually owns the backoff, you probably want internal handling instead — drop throttle.delegate and use retry + throttle.

Related