502

API problem detail

Bad Gateway

Description

This problem happens when an internal DirecFunds service behind the gateway failed, timed out, or returned a server error. The body is a generic Problem Details "upstream service error"; internal error details are never relayed. A dependency that keeps failing surfaces quickly as 502 rather than a hung call.

For a write, the outcome is unknown. A retried write whose first attempt failed this way can return the same 502 again, because the recorded failure is replayed for the original key; the response does not say whether it is a replay.

Response errorCode: UPSTREAM_UNAVAILABLE.

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

  1. Treat the outcome as unknown. A 500 or 502 on a write does not prove that nothing happened: the change may have been applied before the failure.
  2. Read authoritative state first. For a bundled create, look the request up with GET /DisbursementRequests?clientReference={clientReference}; for a granular create, use GET /Disbursement?externalReference={externalReference}. For an action on an existing request, read GET /DisbursementRequests/{id} or GET /Disbursement/{id}/Readiness.
  3. If it did not happen, retry only with the same X-Idempotency-Key and a byte-identical body. For disbursement, pay-in, pay-out, and Disbursement Request creates and actions, and for bank-account $Verify, DirecFunds records a failed keyed write against its key. A same-key retry replays that recorded failure for up to 48 hours instead of running the operation again (the granular POST /Disbursement/$CreateWithLegs is the exception: a same-key retry returns the request if it was committed). Other writes, such as address, branch, user, phone number, Target Account, and bank account creates and updates, are not replay-protected: read or list the resource back before retrying.
  4. Know when to stop. If same-key retries keep returning the same 5xx, stop retrying and email support@direcfunds.com with the traceId from the body (also returned in the X-Trace-Id header).
  5. Use a new key only after confirming that nothing was created or changed. A new key starts a second, independent operation and can duplicate a payment.
  6. Safe reads (GET) may be retried with exponential backoff, starting around 1 second and capped around 30.
Back to all problem details