STITCH_VALIDATION

What you'll see

A stitch with an input or output schema throws a StitchError. Where it throws tells you which side failed — and the two sides report very differently:

• Input, before the request. When call input doesn't match the input schema, the stitch fails fast — the error is thrown before any network call, so nothing leaves the process. The message names the failing slot and issue (invalid body: name is required), and the error carries attempts: 0 with no status. This is the common case for a malformed params, query, body, or headers.
• Response, after the request. When the response doesn't match output, the error is thrown after the response returns and has been transformed and picked — the request did go out. The message is the generic contract violation (drift) and the status is the upstream one (a 2xx: the response arrived, the contract broke). The failing path is not on the error — it rides the drift event on the event stream, as a finding with level: 'error' and change: 'invalid'.

Why it happens

The value didn't satisfy the schema you adapted onto the config:

• Input didn't match input. A required field is missing, a field has the wrong type, or an extra/renamed field tripped a strict schema — checked against { params, query, body, headers } before the request.
• Response didn't match output. A real contract mismatch: the API dropped a field you require, returned a field with the wrong type, or changed a shape your output schema declares. The validator reports each issue with its path.

How to fix

Find the failing path, then check it against the schema:

• If input failed, the path is in the message — fix the call input, or relax the input schema if the field really is optional. The request never went out, so there's nothing to retry once the input is correct.
• If the response failed, read the path off the drift event rather than the message, then decide whether the schema or the API is wrong. Update the output schema to match the real payload, or fix the expectation if the API contract genuinely changed.

For a response whose shape shifts in noisy-but-nonbreaking ways, don't reach for hard validation — a single new optional field shouldn't throw. Pass a drift() spec to output instead, which reports leveled findings without failing the call.

Assign the schema straight to input/output — a Zod schema, any Standard Schema (Valibot, ArkType), or a plain predicate goes on the config as written, and the engine adapts it internally:

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

const createUser = stitch<{ id: number; name: string }>({
    method: 'POST',
    baseUrl: 'https://api.example.com',
    path: '/users',
    // Validated before the POST is sent — bad input fails fast.
    input: { body: z.object({ name: z.string() }) },
    // Validated after the response returns.
    output: z.object({ id: z.number(), name: z.string() }),
});

See Bring your own validator for adapting non-Zod schemas, and Validation for how input and output are checked.

Related