menu

Payment API

What's on this page

General / Error Handling

Error Handling

In case of an error, we respond with a corresponding HTTP status code. The body of the response will be an error in JSON.

Error Response

  • Status Code: Dependent on the type of error: see HTTP Status for possible values
  • Content Type: application/json
  • Content: Error

HTTP Status

Code Message Description
400 Bad Request Invalid input in the request
401 Unauthorized None or invalid API key (typo, expired)
404 Not Found Invalid URL
415 Unsupported Media Type Not using application/json as the content type
500 Internal Server Error Unexpected error
504 Gateway Timeout Processing the request took too long. Default time out is ${timeout} ms

Error object

All resources will return a JSON object in case of an error.

Name Description
type Possible values: input_error, process_error, unexpected_error
message A generic message. Contains helpful information regarding the cause of the error. This message should not be parsed.
In case of input_error this field holds the validation message for the field mentioned in field
field In case of type input_error the field that caused an error. Otherwise not present.
If multiple field validations failed, field contains the first one.
fields In case of type input_error an array of all failed field validations. For each field the error message is shown. See example below.
reference A reference that you can provide to the helpdesk for investigation of the failing request
failureCode An optional field that explains more about the cause of the failure. Possible values: Failure Codes
transactionReference In case of a time out or other processing error, an optional transaction reference to query the status of the transaction.
balance Object containing the merchant’s balance associated with the used payment method. Only included in case of type process_error for failureCode unsufficient_balance.

Example of one input error due to an invalid amount

{
  "type" : "input_error",
  "message" : "'113.73999999999' has a scale larger than 2",
  "reference" : "718ee617",
  "field" : "amount"
}

Example of a process error due to an invalid balance for a requested refund

{
  "type": "process_error",
  "message": "Refund request with amount 20,05 DENIED for originalReferenceId I230504161044674CB87E1BB.F due to insufficient open amount",
  "reference": "5c0a0487",
  "failureCode": "unsufficient_balance",
  "balance": {
    "creditAmount": 0.35,
    "debitAmount": 1.70,
    "total": 1.35
  }
}

Example of multiple input errors

{
  "type" : "input_error",
  "message" : "An amount is required",
  "reference" : "718ee617",
  "field" : "amount",
  "fields": [
    {
      "field": "amount",
      "message": "An amount is required"
    },
    {
      "field": "method",
      "message": "A supported method is required"
    },
    {
      "field": "method",
      "message": "may not be null"
    },
    {
      "field": "currency",
      "message": "A ISO 4217 currency code is required"
    }
  ]
}

Failure Codes

All error responses with failure codes are HTTP Status Code 400: Bad Request.

Name Description
expired The transaction is expired which can happen if remote services such as iDEAL or PayPal expire the transaction on their side
processing_error A general error if the transaction can’t be processed correctly
invalid_config The configuration of the merchant or method is not correct
cancelled The transaction is cancelled by either the customer or the merchant. The field cancelledBy indicates the initiator of the cancel
unsufficient_balance In case of refunds, the transaction can be denied if the balance of the merchant is insufficient
fraud_detected The transaction is denied due to fraud prevention
rejected The transaction is manually confirmed and rejected
unknown_reference The reference used is not known
refund_limit The refund limit for this transaction has been reached, not further refunds are allowed for this transaction
unsupported_currency The currency in your request is not supported
qr_failed There was a problem with the required QR-Code
card_refused The transaction is declined because the card host refused/declined the transaction
insufficient_funds The transaction is declined because the customer has insufficient funds available
vault_token_expired Either the vault access token or the card data attached to the vault access token is expired
amount_limit_exceeded The transaction amount exceeds the configured limit
bad_credentials The provided authentication credentials in your request are incorrect
authentication_failed The transaction is declined because the authentication of the customer failed
duplicate_request A request is performed twice for an action that can only be performed once. For example a second reversal
original_transaction_archived A request with a link to an original transaction is denied if the original transaction is already archived. Requests with a link to an original transaction are for example reversal and refund
soft_declined The transaction failed because additional authentication cannot be performed

Example of a Process error due to invalid method configuration with failure code

{
  "type" : "process_error",
  "message" : "The request could not be processed",
  "reference" : "dfa865b6",
  "failureCode" : "invalid_config"
}