Handling Errors

Xfers will use conventional HTTP response codes to indicate success or failure of an API request.

  • Codes in the 2xx range should indicate success.
  • Codes in the 4xx range should indicate an error that failed given the information provided
    • eg. a required parameter was omitted
    • eg. a charge failed
  • Codes in the 5xx range should indicate an error with Xfers' servers.

Some 4xx errors that could be handled programmatically (e.g. bank declined payments) will include an error code that briefly explains the error reported.

Generic Errors

Here is a list of possible error codes, and some information on how to resolve them.

Error Code




Internal server error

This is rare. Contact Xfers if you see this error in your response.


Access denied

You did not authenticate successfully for the API call you were trying to make.

Please check your authentication credentials. See Authentication


Feature not supported

The functionality you are trying to use is not supported.

Please check that the functionality is available for the locale or environment you are making the request to.


Record not found

The object you were looking for based on your API request parameters was not found.

Please check the id that you've used for the request.


Invalid parameters

Your request parameters are invalid.

Please check the format of your request parameters, or check that the parameters are within limits.


Unknown error

This is very rare. Please inform the Xfers team if you receive such a response.

Transaction Specific Errors

Error Code

Error Description

Error Details


Account has insufficient funds

The account you are trying to perform a transaction from does not have enough funds.

Make sure that a deposit is made to the account in order to proceed.


Invalid transaction amount

The transaction amount requested is either below the minimum, or above the maximum limits.

Please check the limits of the transaction type you are trying to perform before re-trying.


Transaction exceeds account transaction limit

The transaction you are trying to perform will cause the account to exceed its transaction limits.

The account will no longer be able to perform transactions until its limits are reset.


Transaction exceeds account balance limit

The transaction you are trying to perform will cause the receiving account to go past its account balance limits.

The account will not be able to receive funds unless the amount will not cause it to exceed the account balance limit.


Payer is not the same KYC-ed user.

The transaction is sent by a different individual. Hence, it is blocked by Xfers.

Xfers will reach out to you to receive more documents from user to prove that the KYC-ed user is the payer.


Transaction is under investigation by Xfers.

The transaction is flagged internally by Xfers for investigation.


Amount exceeds limitations.

The transaction amount exceeds limit.


Bank account is unverified.

The bank account used to make the transfer is unverified.


Amount is wrong.

The transaction amount is wrong.

Used for Dynamic Virtual Account (VA) payment method. Error code appears when the transferred amount is different from the amount indicated in the transaction.

Did this page help you?