Error handling

Learn how to handle basic Unzer API errors.

For a complete list of all possible Unzer error codes, go to the error codes reference page.

HTTP response status codes

To indicate a success or failure of an API request, the Unzer API uses standard HTTP response status codes.

You can encounter the following classes of response status codes:

Code class Meaning Example
1xx Information 100 Continue
2xx Success 200 OK
3xx Redirection 300 Moved Permanently
4xx Client error 400 Bad Request
5xx Server error 500 Internal Server Error

Error response structure

HTTP error codes are always returned with precise information about the origin of the error, in the form of a JSON object.

Inside the JSON object, you’ll find a detailed list of all possible problems.

{
    "url": "https://dev-api.unzer.com/v1/customers",
    "timestamp": "2018-09-22 18:10:49",
    "errors": [
        {
            "code": "API.410.200.004",
            "merchantMessage": "First name  is missing",
            "customerMessage": "First name is missing. Please contact us for more information."
        },
        {
            "code": "API.410.200.007",
            "merchantMessage": "Salutation must be mr, mrs or unknown",
            "customerMessage": "Salutation is invalid. Please contact us for more information."
        },
        {
            "code": "API.410.200.011",
            "merchantMessage": "Birth date must be in yyyy-MM-dd or dd.MM.yyyy",
            "customerMessage": "Invalid birth date. Please contact us for more information."
        },
        {
            "code": "API.410.200.001",
            "merchantMessage": "Last name is missing",
            "customerMessage": "Last name is missing. Please contact us for more information."
        }
    ]
}

Each error entry contains two or three elements:

Element Description
code The code of the error. For details, see code structure.
merchantMessage An explanation of the error, and further information meant for you as a merchant.

The merchantMessage is not intended to be displayed to the customer, and is always in English.

The merchantMessage is only visible if you made the call with a private key. If you made the call with a public key, the merchantMessage field is missing.
customerMessage A message displayed to the customer.

The customerMessage displays in the language set in the Accept-Language header shown to the customer.

Error code structure

Each error code is made of four parts, for example:

"code": "API.410.200.004"
API 410 200 004
Meaning Origin of the error Resource that caused the error Category of the error Error ID
Possible values API
The error was produced by the Unzer API.

COR
The error was produced by the Unzer Core System.

SDM
The error was produced by the SDM System.
0xx Generic error
1xx Generic error
2xx Generic error
31x /payments
32x /payments/authorize
33x /payments/charges
34x */cancels
35x /payments/chargeback
36x /payments/shipments
37x /payments/payouts
41x /customers
51x webhooks
60x /basket
61x /paymentpage
62x /store_types
63x /linkpay
64x /types//recurring
71x /types/card
72x /types/sepa-direct-debit
73x /types/sepa-direct-debit-secured
74x /types/paypal
75x /types/sofort
76x /types/invoice
77x /types/invoice-secured
78x /types/prepayment
79x /types/ideal
80x /types/giropay
81x /types/przelewy24
82x /types/eps
83x /types/pis
84x /types/invoice-secured
85x /types/banconctact
86x /types/installment-secured
87x /types/alipay
88x /types/applepay
89x /types/wechat
9xx Not in use

Error code examples

Example Meaning
API.410.200.004 An API-based error, caused by the /customers resource, with an ID 004
COR.870.200.079 A core-based error, caused by the /types/alipay resource, with an ID 079
SDM.630.200.088 An SDM-based error, caused by the /linkpay resource, with an ID 088

Third-party errors

Even if your request is valid and the Unzer API doesn’t return an HTTP error, there may be a problem when communicating with third-party systems.

If that happens, you receive a success HTTP response (within the 2xx range), with additional status information:

{
  "id" : "s-err-b6dda32b447246ec9f28f90a910",
  "url" : "https://api.unzer.com/v1/payments/charges",
  "timestamp" : "2019-08-09 13:17:24",
  "errors" : [ {
    "code" : "COR.800.100.190",
    "merchantMessage" : "transaction declined (invalid configuration data)",
    "customerMessage" : "Your payment was not successfull. Please contact us for more information.",
    "status" : {
      "successful" : false,
      "processing" : false,
      "pending" : false
    },
    "processing" : {
      "uniqueId" : "31HA07BC819912251EB623E2D7290464",
      "shortId" : "4292.8304.3120"
    }
  } ]
}
Element Description
code The code of the error. For details, see code structure.
merchantMessage An explanation of the error, and further information meant for you as a merchant.

The merchantMessage is not intended to be displayed to the customer, and is always in English.

The merchantMessage is only visible if you made the call with a private key. If made the call with a public key, the merchantMessage field is missing.
customerMessage A message displayed to the customer.

The customerMessage displays in the language set in the Accept-Language header shown to the customer.

Retrieve errors by ID

You can retrieve each error that you received in the past, by using its unique id.

To retrieve an error, make a GET call to the following URL:

https://api.unzer.com/v1/errors/[error-id]
curl -X GET https://api.unzer.com/v1/errors/p-err-85a6611365354a94ab55682d7c5  \
-u s-priv-xxxxxxxxxx:
{
  "id" : "p-err-85a6611365354a94ab55682d7c5",
  "url" : "https://api.unzer.com/v1/types/card",
  "isSuccess" : false,
  "isPending" : false,
  "isError" : true,
  "timestamp" : "2019-10-02 08:40:51",
  "errors" : [ {
    "code" : "COR.800.400.205",
    "customerMessage" : "Your payment was rejected. Please use another payment method.",
    "merchantMessage" : "Geographical Check - GeographicBinIp: NOT PASSED (Countries= address: DE ip: US bin: CZ",
  } ]
}