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.

The code-to-docs contract

Each catalog page below owns a stable code (STITCH_VALIDATION, STITCH_DRIFT, and so on). The code's page slug is its URL — the failure documented at /errors/<slug> is the page the runtime will deep-link to from a thrown error. Slugs are an API: once a page is published its slug is never renamed, only added-and-redirected, so a link a runtime emitted a year ago still resolves.

Every coded failure

See also