400 / 409

API problem detail

Preflight

Description

This 400 (payload/setup) or 409 (bundled-action state) response means the request failed a server-side preflight rule. For a disbursement, that can include source-account readiness, recipient details, a duplicate clientReference, or the selected rail's routing-number eligibility. Changing the bank details of a Target Account that is a pay in's funding source is also refused here: update the managed bank account, then delete and recreate the pay in. No disbursement request is created by a rejected atomic create. The validationFailures list names each field.

This refusal is different from the advisory preflight object in the 200 response of POST /DisbursementRequests/$Validate. That object reports findings (for example InputRequired) without refusing anything; this problem type is a hard refusal.

Response title: The request did not pass preflight inspection..

Experience API error bodies also carry errorCode, resolution, and traceId. Branch on errorCode, not on title or detail; see fields on every error.

How to resolve

Read the response's validation failures and correct the named field. An RTP or FedNow routing-number failure means the selected network could not be confirmed for that number; DirecFunds will not switch rails automatically. Confirm the destination details with the recipient and deliberately select a supported rail. Send the corrected request with a new X-Idempotency-Key: the same key with a different body returns 422 Idempotency Conflict. Before retrying a create whose outcome is uncertain, read the request by its clientReference and reuse the same idempotency key only for the same payload.
Back to all problem details