Errors & pitfalls

When a stitch can't produce a result, it fails with a StitchError — an Error with name: 'StitchError', a human-readable message, and an optional .status carrying the upstream HTTP status. Await a stitch and that error is what catch receives:

import { stitch } from 'stitchapi';

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

try {
    await me();
} catch (e) {
    if (e instanceof Error && e.name === 'StitchError') {
        const status = (e as Error & { status?: number }).status;
        console.error(e.message, status);
    }
}

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.

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