Errors

Type of errors

There are two types of errors when making payments with Devengo:

errors before the payment has been processed
errors occurred during payment processing by the banking network

The first group includes errors generated by Devengo for different reasons, from validation errors to technical problems. In contrast, the second group contains errors returned by the banking system once the payment has been sent for processing. This second group includes bank communication problems, destination account problems, etc.

Errors before the payment has been processed

Most of these errors will be returned immediately in the body of the response when you try to create a payment. You will receive a 4XX response with a detailed explanation of the error in its body. It's important to note that the payment has not been created in this case.

{
  "error": {
    "message": "Invalid account number",
    "code": "invalid_account_number",
    "type": "invalid_request_error"
  }
}

There are other potential errors in our validation phase or due to technical problems in our systems. Since it happens in the background, you will receive them as webhook notifications.

Errors during payment processing

As we said before, those payment has been executed, but the money couldn't be credited to the third party. You will have access to the original error code from the banking network. Still, since those codes aren't always as straightforward as they should be and they change from one network to another, we have our own error code that will help you to understand not only what the error means but also if they are definitive, if you can resend the same payment and what to do next.

Error code	Error type	Retryable	Description
ERR-0001	blocked_account	🚫	The account is temporarily blocked and cannot accept money. User can contact her local branch to unfreeze the bank account
ERR-0002	closed_account	🚫	The account is closed and cannot accept money. User should provide a new bank account
ERR-0003	integration_error	🚫	This is normally an integration error between banks. It might sound crazy but banking rules are subject to interpretation and this might happen
ERR-0004	invalid_bank	🚫	The bank doesn't exist in this banking network anymore. This can happen with banks after mergers and acquisitions and the user has probably received a new bank account number
ERR-0005	recoverable	✅	There is a communication error inside the banking chain. You could resend this transaction after a few minutes although this error could last for a few hours sometimes
ERR-0006	suspended_bank	🚫	Destination bank has been removed from the banking network temporarily. This problem normally appears in the instant payment networks so normally you will redirect this payment as non-instant
ERR-0007	wrong_account_number	🚫	The account number is invalid. User should be contacted for a new bank account
ERR-0008	wrong_amount	🚫	The amount is invalid. You should check and fix the request
ERR-0009	wrong_operation_code	🚫	Duplicated operation. You should check and fix the request
ERR-0010	other	🚫	Other reasons. The exact reason is not specified due to privacy laws, but most of the time should be handled like a `blocked_account`
ERR-0011	processor_failure	✅	The payment could not be processed because of an unknown failure.
ERR-0012	transaction_reversed	🚫	Transaction was processed but reverted by destination bank for any reason. The exact reason is not specified due to privacy laws, but most of the time should be handled like an `account_been_closed`
ERR-0013	payment_denied	🚫	Payment was denied because it could not pass some validation. Most of the time a payment is denied if the amount limits that have been previously configured are exceeded.

Since our processing of transactions is always in the background, you will receive those errors in the tag error of our webhooks or whenever you ask for the details of a payment that has been rejected o reversed previously.

{
  "code": "ERR-0001",
  "type": "blocked_account",
  "reason": "AG01"
}

Field reason will only be shown for banking network errors.

Detailed errors for each network

If you need fine-grained handling of errors coming from the banking system you might use the original error code generated by your payment. You can find a detailed explanation for them in the following URLs.

SCT
SCT-Inst

Testing your code

You can find in our API documentation a list of IBANs that you can use to force some of these errors in our sandbox.