Transfer Failures

The error codes on a failed transfer, what each one means, and what you or your recipient can do next.

When a transfer fails, Dots sets status to failed, reverses the transfer’s wallet transactions, and adds two fields to the transfer object:

Field	Description
`error`	Stable code from the table below. Branch on this field.
`error_message`	Client-safe description of the failure. Dots may change the wording, so don’t parse it. Whether to show it to a recipient, a payer, or a vendor depends on the transfer; see the guidance below.

Transfers without an error omit both fields. You receive them from Get a Transfer and List all Transfers. When a transfer.updated webhook arrives, fetch the transfer to read its current error.

Failed transfer (excerpt)

{
  "id": "5f2c1a8e-7d3b-4c6a-9e1f-2b8d4a6c0e37",
  "status": "failed",
  "error": "account_closed",
  "error_message": "The receiving account is closed."
}

Dots may add codes. Handle a code you don’t recognize the same way you handle unknown.

Payout Failures

This table covers payouts to a recipient, where the transfer has a user_id. The Who acts column names who can fix the failure: your recipient, you, or Dots. For app wallet withdrawals, refills, payments, and clawbacks, see Bank Account Debit and Withdrawal Failures. For wallet-to-wallet transfers and vendor payables, see Wallet Transfer and Payable Failures.

Code	Meaning	Who acts	Suggested action
`account_closed`	The receiving account is closed.	Recipient	Ask the recipient to add a different payout method, then send the payout again.
`account_not_found`	The receiving bank or provider can’t find the account.	Recipient	Ask the recipient to check their account details and connect the account again.
`invalid_account_details`	The account or routing details are invalid.	Recipient	Ask the recipient to re-enter their account details.
`name_mismatch`	The recipient’s name doesn’t match the name on the account.	Recipient	Ask the recipient to connect an account in their own legal name.
`account_blocked`	The receiving account can’t accept this transfer.	Recipient	Ask the recipient to contact their bank or add a different payout method.
`transfer_refused`	The receiving bank, card issuer, or payout provider refused the transfer.	Recipient	Ask the recipient to contact their bank or card issuer, or add a different payout method.
`limit_exceeded`	The transfer exceeds a limit on the receiving account.	Recipient	Send a smaller amount, or ask the recipient to use a different payout method.
`amount_too_small`	The amount falls below this destination’s minimum.	You	Send a larger amount, or ask the recipient to use a different payout method.
`amount_too_large`	The amount exceeds this destination’s maximum.	You	Split the payout into smaller transfers, or ask the recipient to use a different payout method.
`destination_not_supported`	Dots can’t pay out to this bank, country, or currency.	Recipient	Ask the recipient to add a different payout method.
`recipient_info_required`	The provider needs more information about the recipient, or the recipient has to verify their payout account.	Recipient	Ask the recipient to update their details, for example through a Flow, or to verify their payout account with the provider, such as PayPal. Then send the payout again.
`declined_for_risk`	The provider declined the transfer.	Dots	Don’t send the payout again. Contact Dots support with the transfer ID.
`card_unusable`	The receiving card can’t accept this transfer.	Recipient	Ask the recipient to add a different card or payout method.
`temporarily_unavailable`	The provider couldn’t complete the transfer this time.	You	Send the payout again later.
`unknown`	Dots has no more specific code for this failure.	Dots	Contact Dots support with the transfer ID.

The API defines recipient_action_required for a payment that PayPal holds until the recipient chooses how to receive it. Dots keeps that transfer pending and doesn’t return the code today, so you don’t need to handle it yet.

To send a failed payout again, create a new payout with a new idempotency key. If the recipient has to act, the new payout fails again until they make the change.

Bank Account Debit and Withdrawal Failures

Some transfers move money between Dots and a bank account that isn’t a recipient’s payout method. For these, the code describes that bank account. error_message uses the same wording for every transfer type and calls that account the “receiving account” even when Dots debited it, so write your own text from the code rather than showing the message as is.

A refill adds funds to your app wallet from your bank account.
A payout with no user_id is an app wallet withdrawal to your bank account.
A payment debits the payer’s bank account. You create one with Create a Payment, and the payer is the user or payment customer in that request.
A clawback is a payment with metadata.type set to clawback. It debits your recipient’s bank account.

Code	Refill or app wallet withdrawal	Payment or clawback
`insufficient_funds`	For a refill, add funds to your bank account.	Ask the payer to add funds to their bank account.
`account_closed`, `account_not_found`, `invalid_account_details`, `account_blocked`	Update the bank account linked to your app in the Dots dashboard.	Ask the payer to check or replace their bank account.
`transfer_refused`	Ask your bank to accept transfers to and from Dots.	Ask the payer to contact their bank.
`unknown`	Contact Dots support with the transfer ID.	Contact Dots support with the transfer ID.

To retry:

For a refill you created with Deposit Funds into App Wallet, call it again with a new idempotency key.
For a refill from an ACH credit or wire you sent from your bank, send the funds again from your bank.
For a withdrawal, call Withdraw Funds From App Wallet again with a new idempotency key.
For a payment, call Create a Payment again once the payer has fixed their bank account. It doesn’t take an idempotency key, so check that you haven’t already created the replacement.
For a clawback, contact Dots support with the transfer ID.

Wallet Transfer and Payable Failures

A balance transfer moves funds between wallets. When Create a Transfer can’t move the funds, it rejects the request with a transaction error and creates no transfer. Inside a Create a Transfer Batch request, an item Dots can’t fund creates a failed balance transfer instead, so the other items continue. The batch item’s error field holds the failure message itself, for example that the source wallet doesn’t have enough funds, and the item has no error_message. The linked transfer, which you can fetch with the item’s transfer_id, has error set to unknown and the same text in error_message. Add funds to the source wallet, then submit the item again in a new batch with a new idempotency_key on the item, and a new batch-level idempotency_key if you set one. A new batch-level key alone isn’t enough: an item that reuses the failed item’s key returns the same failed transfer.

A payable transfer pays a vendor through Accounts Payable. It fails with unknown and an error_message when your app wallet can’t cover the amount and fee, or when the provider refuses the transfer. If the provider later reports an ACH failure, error may carry one of the account codes from the payout table, such as account_closed. Today that code comes from the funding side of the payable, so for a payable funded from your bank account it describes your account, not the vendor’s. Dots doesn’t yet return a separate code for a return from the vendor’s bank. The payable’s status becomes payment_failed. Fix the cause, for example by adding funds to your app wallet or updating the bank account linked to your app, then call Pay a Payable again. If the cause isn’t clear, contact Dots support with the transfer ID.

Payout Failures

Bank Account Debit and Withdrawal Failures

Wallet Transfer and Payable Failures

On this page