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);
    }
}

instanceof holds while the error and the check share one copy of stitchapi. Two copies can meet in one process: a CommonJS build, where each stitchapi/* subpath carries its own copy of the class, or two installed versions. Where that can happen, check with isStitchError(e) instead. It is true for StitchError and every subclass, RateLimitError included, and it is the check every @stitchapi/* host adapter's stitchError.is starts from:

import { isStitchError } from 'stitchapi';

function describeFailure(e: unknown): string {
    return isStitchError(e) ? `upstream ${e.status ?? 'unreachable'}` : 'bug';
}

The guard is strict: an Error that only borrows name = 'StitchError' is not a stitch error to it, so build test doubles with new StitchError(…). The host adapters also accept an Error with that name or RateLimitError, so a failure from a copy of stitchapi that predates the guard still gets the host's generic default body instead of reaching the framework's own error handling.

JSON.stringify(err) — and a logger that serializes through it — emits a StitchErrorResult, { name, message, status?, attempts, url? }, built to be logged: message is included, and both it and url have URL credentials scrubbed — userinfo removed, secret query values (api_key, access_token, …) replaced with REDACTED. A transport error for a malformed URL quotes the whole request URL in its message, which is why the message is scrubbed too. .body, .cause and a RateLimitError's raw .response (headers, set-cookie included) are left out, because they are unredacted upstream data; a RateLimitError adds retryAfter. Read err.body and err.url directly when you mean to.

What that does not cover: a secret the upstream or an adapter wrote into message in a shape that is not a URL (a bare token in an error text), and any logger that does not call toJSON.

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 throwingCopy Anchor Link

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 valuesCopy Anchor Link

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 runtimeCopy Anchor Link

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 failureCopy Anchor Link

See alsoCopy Anchor Link