Errors & pitfalls

When a stitch can't produce a result, it fails with a StitchError — an Error subclass exported from stitchapi, carrying a human-readable message, an optional .status (the upstream HTTP status), and .attempts (how many tries the runtime made before giving up). When the failure came from an HTTP response it also carries .body (the parsed error payload — an API's { error: "…" }) and .url (the final request URL, after redirects); both are undefined for transport/internal errors. Await a stitch and that error is what catch receives — narrow it with instanceof:

import { StitchError, stitch } from 'stitchapi';

const me = stitch({
    baseUrl: 'https://api.example.com',
    path: '/me',
});

try {
    await me();
} catch (e) {
    if (e instanceof StitchError) {
        // .body is the parsed error payload; .url is the final request URL.
        console.error(e.message, e.status, e.attempts, e.body, e.url);
    }
}

If you read the event stream instead of awaiting, the same failure arrives as an error event carrying { name, message, status?, attempts, at } — attempts is how many tries the runtime made before giving up, at is when it gave up.

Handle failure without throwing

await and .unwrap() throw on failure. When you'd rather branch than wrap the call in try/catch, .safe() consumes the call and never throws — it resolves to a discriminated { ok, data, error }, where error is the same StitchError, or null on success:

import { stitch } from 'stitchapi';

const me = stitch({ baseUrl: 'https://api.example.com', path: '/me' });

const { data, error } = await me.safe();
if (error) console.error(error.status, error.attempts);
else console.log(data); // the validated result; error is null here

.unwrap() is the explicit throwing twin of .safe() — the value, or a thrown StitchError, exactly like awaiting the bare call. See the event stream for the iterate-instead-of-await view of the same outcomes.

Catalog IDs are documentation, not runtime values

Each catalog page below is filed under a stable catalog ID (STITCH_VALIDATION, STITCH_DRIFT, and so on), and the ID's page slug is its URL. Slugs are an API: once a page is published its slug is never renamed, only added-and-redirected, so a link written a year ago still resolves.

Telling failures apart at runtime

Every failure arrives as a StitchError except the delegate-backoff rate limit, which is its own exported RateLimitError. So narrow with instanceof first, then branch on .status and .attempts — together they separate every failure mode in the catalog:

import { RateLimitError, StitchError, stitch } from 'stitchapi';

const report = stitch({ baseUrl: 'https://api.example.com', path: '/report' });

try {
    await report();
} catch (e) {
    if (e instanceof RateLimitError) {
        // The one catalog entry that IS a runtime identity of its own. It
        // subclasses StitchError, so this arm MUST come before the one below —
        // otherwise the generic arm swallows it.
        console.error('back off for', e.retryAfter);
    } else if (e instanceof StitchError) {
        if (e.attempts === 0) {
            // Nothing left the process: bad input, or the breaker is open.
            console.error(e.status === 503 ? 'circuit open' : 'bad input');
        } else if (e.status !== undefined && e.status < 300) {
            // A 2xx that still failed: the body broke the declared contract.
            console.error('contract violation', e.status);
        } else {
            console.error('upstream failed', e.status ?? 'no response');
        }
    }
}

Two catalog IDs share one runtime failure: a plain output schema failure (STITCH_VALIDATION) and a hard drift() failure (STITCH_DRIFT) both throw the same contract violation (drift) StitchError. The thrown error does not say which path broke — that detail rides the drift events on the event stream, where a hard failure appears as a finding with level: 'error' and change: 'invalid':

import { drift, stitch } from 'stitchapi';
import { z } from 'zod';

const user = stitch({
    baseUrl: 'https://api.example.com',
    path: '/user',
    output: drift(z.object({ id: z.number() })),
});

for await (const ev of user().stream()) {
    if (ev.type === 'drift' && ev.finding.level === 'error') {
        // The structured signal: which path broke, and how.
        console.error(ev.finding.path, ev.finding.change, ev.finding.detail);
    }
}

Every documented failure

See also