Skip to main content

​
Failure Reference

Some CDP API resources move through an asynchronous lifecycle and can reach a terminal failed state after being accepted. Reading such a resource is still a successful API call — these failures are reported in the response body, not via a 4xx/5xx status. This page documents the machine-readable failure codes for each resource, grouped by resource type, with per-code cause, resolution steps, and retry guidance.

​
Transfers

A GetTransfer or ListTransfers read returns 200 even when the transfer’s status is failed — the read succeeded, the resource’s state is failed. The transfer carries a failureDetails object: failureCode (machine-readable, see below), failureMessage (human-readable), and failureLink (a link back to this page, anchored to the specific failureCode).

​
Risk review rejected

A risk or compliance review rejected the transfer. Steps to resolve:
  1. The transfer will not complete as submitted; do not retry it unchanged.
  2. Contact CDP support with the transferId if you believe this was rejected in error.
Retryable: No.

​
Insufficient balance

The source account did not have sufficient balance to complete the transfer at execution time, even though it passed validation at creation. Steps to resolve:
  1. Confirm the current balance of the source account.
  2. Once funded, create a new transfer — the failed transfer itself cannot be re-executed.
Retryable: No, not until the source account is funded, and only via a new transfer.

​
Quote validation failed

The transfer’s quote failed re-validation at execution time, for example because market conditions changed between quoting and execution. Steps to resolve:
  1. Create a new transfer to obtain a fresh quote.
  2. Execute the new transfer promptly, before it expires.
Retryable: No, create a new transfer instead of retrying this one.

​
Validation failed

A generic business validation rule failed during execution. Steps to resolve:
  1. Review failureMessage for the specific rule that failed.
  2. Contact CDP support with the transferId if the cause is unclear.
Retryable: Depends on the underlying rule; see failureMessage.

​
Timeout

The transfer timed out waiting for a downstream step to complete within the allotted completion window. This is a terminal state: the transfer will not resolve asynchronously once it has reached failed with this code. Steps to resolve:
  1. Treat the transfer as terminally failed; it will not transition out of failed.
  2. Create a new transfer if you still want to move the funds.
Retryable: No, this transfer is terminal; create a new transfer instead of retrying this one.

​
Reversed

The funding deposit backing this transfer was reversed (for example, an ACH return or chargeback) before the transfer completed. Steps to resolve:
  1. Resupply the source funds through a new, valid deposit.
  2. Create a new transfer once funds are confirmed.
Retryable: No, until the source funds are resupplied.

​
Provider error

A downstream payment provider or rail failed the transfer for a non-retryable reason not otherwise categorized. Steps to resolve:
  1. Contact CDP support with the transferId and failureMessage.
Retryable: No, unless CDP support indicates otherwise for this specific case.

​
Internal error

An internal orchestration error caused the failure. This is not a fault in your request. Steps to resolve:
  1. Create a new transfer.
  2. Contact CDP support with the transferId if the error persists.
Retryable: No, this transfer is terminal; create a new transfer instead of retrying this one.

​
Capability rejected

The account is not permitted to move money this way, for example because it is restricted. Steps to resolve:
  1. Resolve the underlying restriction before attempting another transfer.
  2. Contact CDP support if you believe the restriction is incorrect.
Retryable: No, until the restriction is lifted.

​
Generic failure

The transfer failed for a reason that has not been categorized into a specific failure code. This is the catch-all used when no more specific failureCode applies; failureMessage carries the available detail. Steps to resolve:
  1. Read failureMessage for the specific reason.
  2. Contact CDP support with the transferId and failureMessage if the cause is unclear.
Retryable: No. Do not retry the same transfer; if failureMessage indicates a transient cause, create a new transfer instead.