Error reference
Problem details
Match an API response to its meaning, then follow the recommended resolution. Branch on the response’s errorCode; see fields on every error.
Request errors
Review authentication, permissions, routes, and request data.
Server errors
A write’s outcome may be unknown: read authoritative state before retrying, retry only with the same key and body, and stop and contact support if the same error repeats.
Internal or legacy types
Not returned by the Experience API. Kept so older links resolve; each page names the response you receive instead.
No matching errors. Try a status code such as “400” or a shorter phrase.
Fields on every error
Experience API error responses carry these fields in addition to the standard type,
status, title, and detail. The money-movement refusals that use a
raw 422 body also carry errorCode, resolution, and traceId.
| Field | Meaning |
|---|---|
errorCode |
Stable machine-readable code. Branch on this, not on title or
detail, which are human-readable and may change. Specific codes include
INVALID_IDEMPOTENCY_KEY, REQUEST_IN_PROGRESS,
IDEMPOTENCY_CONFLICT, REVIEW_CONFIRMATION_REQUIRED,
BILLING_PAYMENT_METHOD_REQUIRED, and the
money-movement codes. Otherwise the code
follows the status: INVALID_REQUEST (400), AUTHENTICATION_REQUIRED (401),
PERMISSION_DENIED (403), RESOURCE_NOT_FOUND (404),
STATE_CONFLICT (409), PRECONDITION_FAILED (412),
REQUEST_REFUSED (422), PRECONDITION_REQUIRED (428),
RATE_LIMITED (429), SYSTEM_ERROR (500), and
UPSTREAM_UNAVAILABLE (502).
|
resolution |
What to do next: category, owner (for example
Integrator, CompanyAdministrator, Approver, or
DirecFunds), retryMode (CheckStatus,
SameIdempotencyKey, RefreshState, RetryAfter,
Reauthenticate, or DoNotRetryUnchanged), and a plain-language
nextAction.
|
traceId |
The same value as the X-Trace-Id response header. Quote it when you email support@direcfunds.com. |
validationFailures |
Field-level failures, each with propertyName and errorMessages, on validation and preflight refusals. |
A few responses do not point to a page in this reference:
-
POST /DisbursementRequestsandPOST /DisbursementRequests/$Validatereturn400with a bare code as thetypewhen DirecFunds cannot resolve the payment branch:PAYMENT_BRANCH_SELECTION_REQUIRED(nobranchIdsent and more than one branch is eligible; send one),REQUESTED_BRANCH_NOT_AUTHORIZED,NO_ELIGIBLE_PAYMENT_BRANCH,INTEGRATION_NOT_AUTHORIZED, orPAYMENT_BRANCH_RESOLUTION_FAILED. Thedetailexplains which. -
A refusal the gateway cannot classify more precisely returns an empty
typewith the title Request Refused. Use itsstatus,errorCode, andresolution. -
An unsupported HTTP verb returns
405with the standard typehttps://tools.ietf.org/html/rfc9110#section-15.5.6, and a framework binding error (such as malformed JSON) returns400withhttps://tools.ietf.org/html/rfc9110#section-15.5.1and anerrorsmap.