Failure causes

When a transfer fails, its failure cause is added to the transfer object returned by the API, in the failureCause field (code, message and params).

Important

These are application errors, unrelated to HTTP status codes.The HTTP status codes returned by each HUB2 API endpoint are listed in the HUB2 API reference documentation.

The failure causes on this page only concern errors that occur while a transaction is being processed.

New failure causes may be added over time. Handle unknown codes gracefully, for example as a generic failure.

Code	Description
`internal_error`	Transfer failed. Internal error. Our technical team has been notified.
`invalid_amount`	Transfer failed. The amount is invalid. Please refer to the amount policies documentation.
`service_unavailable`	Transfer failed. The provider is currently unavailable.
`service_temporarily_disabled`	Transfer failed. The service is temporarily disabled due to an ongoing incident. Our technical team is working on it.
`too_many_request`	Transfer failed. The provider is receiving too many requests. Please try again later.
`unknown_reason`	Transfer failed. No reason was provided by the provider.
`reconciliation_failure`	Transfer failed. It could not be reconciled or confirmed with the provider.
`fraud_suspicion`	Transfer failed. Fraud suspicion detected by the provider.
`invalid_destination`	Transfer failed. The destination is not valid.
`forbidden_by_provider`	Transfer failed. Refused by the provider.
`forbidden_by_provider_maximum_limit`	Transfer failed. Refused by the provider because a limit was reached.
`forbidden_by_provider_blacklisted_msisdn`	Transfer failed. The recipient MSISDN is blocked by the provider.
`timeout`	Transfer failed. The provider did not respond in time.
`insufficient_funds`	Transfer failed. The merchant does not have enough funds.
`hub2_insufficient_funds`	Transfer failed. Insufficient funds on the HUB2 account at the provider.
`customer_insufficient_funds`	Transfer failed. The debited account does not have enough funds.
`customer_account_locked`	Transfer failed. The recipient account has been locked by the provider.
`unsupported_currency`	Transfer failed. This currency is not supported.
`canceled`	Transfer failed. Canceled by the provider.
`canceled_by_customer`	Transfer failed. Canceled by the customer.
`destination_not_allowed`	Transfer failed. The provider does not allow transfers to this recipient.
`blacklisted_msisdn`	Transfer failed. The MSISDN is temporarily blocked by HUB2. See MSISDN - Blacklist.
`invalid_payment_processor`	Transfer failed. The selected provider does not support this operation.
`duplicate_request`	Transfer failed. A similar operation has just been recorded. Please try again later.
`authentication_failed`	Transfer failed. Authentication with the provider failed.
`bad_parameters`	Transfer failed. The provider rejected the request parameters.
`bad_request`	Transfer failed. The request contains errors or is incorrectly formatted.

Getting started

Transfers

Payments

Webhooks

Processing Only

Payment Links

Submerchants

Other

Important