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.

4xx

Request errors

Review authentication, permissions, routes, and request data.

5xx

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.

Legacy

Internal or legacy types

Not returned by the Experience API. Kept so older links resolve; each page names the response you receive instead.

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.

FieldMeaning
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 /DisbursementRequests and POST /DisbursementRequests/$Validate return 400 with a bare code as the type when DirecFunds cannot resolve the payment branch: PAYMENT_BRANCH_SELECTION_REQUIRED (no branchId sent and more than one branch is eligible; send one), REQUESTED_BRANCH_NOT_AUTHORIZED, NO_ELIGIBLE_PAYMENT_BRANCH, INTEGRATION_NOT_AUTHORIZED, or PAYMENT_BRANCH_RESOLUTION_FAILED. The detail explains which.
  • A refusal the gateway cannot classify more precisely returns an empty type with the title Request Refused. Use its status, errorCode, and resolution.
  • An unsupported HTTP verb returns 405 with the standard type https://tools.ietf.org/html/rfc9110#section-15.5.6, and a framework binding error (such as malformed JSON) returns 400 with https://tools.ietf.org/html/rfc9110#section-15.5.1 and an errors map.