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
-
Treat the outcome as unknown. A
500or502on a write does not prove that nothing happened: the change may have been applied before the failure. -
Read authoritative state first. For a bundled create, look the request up with
GET /DisbursementRequests?clientReference={clientReference}; for a granular create, useGET /Disbursement?externalReference={externalReference}. For an action on an existing request, readGET /DisbursementRequests/{id}orGET /Disbursement/{id}/Readiness. -
If it did not happen, retry only with the same
X-Idempotency-Keyand 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 granularPOST /Disbursement/$CreateWithLegsis 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. -
Know when to stop. If same-key retries keep returning the same
5xx, stop retrying and email support@direcfunds.com with thetraceIdfrom the body (also returned in theX-Trace-Idheader). - 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.
- Safe reads (
GET) may be retried with exponential backoff, starting around 1 second and capped around 30.