Error codes

Check the Unzer API error codes.

HTTP error codes

The Unzer API is entirely organized around REST and therefore uses standard HTTP response codes to indicate the success or failure of an API request.

Codes in the 2xx range indicate success. Codes in range 4xx indicate an error. In rare cases, you may also see codes in the 5xx range that indicate an error on our servers.

Typical HTTP error codes are:

HTTP Code HTTP-Response Possible reasons
400 Bad Request Bad request to the Api e.g. required parameter missing, wrong syntax for parameter
401 Unauthorized Request without a key or with an invalid key
403 Access-Denied/Forbidden Request to a private resource with a public key
404 Not Found Requested resource does not exist.
405 Method Not Allowed Merchant does not configure to use payment method.
Or payment method is not configured to execute specific method.
415 Unsupported media type Request media type is not supported by system.
500 Internal Server Error Unspecified error

A detailed list of all possible HTTP error codes could be found here.

Error codes

HTTP error codes are always returned with information about the origin of the error, in the form of a JSON object. Within the error object there is a list of errors to provide you with all possible problems in a chunk.

Each error entry contains either two or three pieces of information:

key description
code customerMessage
merchantMessage The explanation of the error and further information for you as a merchant. The message is not intended to be displayed to the customer and always appears in English. This message is only visible if you make the call with a private key. If you are using a public key, this field is missing.
customerMessage This is the message displayed to the customer. It is offered in several languages, based on the Accept Language header.
{
    "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."
        }
    ]
}

Error from 3rd party communication

HTTP errors are only displayed if an invalid request is detected. If the request is valid, we will try to process it. Nevertheless, there may be problems communicating with third-party payment systems. In this case, you will receive an HTTP response in the range of 2xx along with some 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"
    }
  } ]
}

The message.merchant message should give you enough insight to understand the problem. It is for internal use only, as it may contain detailed information about the problem that should not be shown to the end customer.

In addition, you will also receive a message.customer notice intended for the end customer. It hides details that should not be displayed to the customer and is delivered in the language set in the Accept-Language header shown to customers and is delivered in the respective language.

Structure of error codes

Errorcodes are returned as 4 tripples. Every tripple has a specific meaning:

Origin Resource Category Error ID Description
API 410 200 004 Means that this is an API based error, that is assigned to an authorization
2nd tripple 410 Describes the resource from which the problem occured.

The origin can be one of the following:

Origin Meaning
API The error was produced by the API
COR The error was produced by the Unzer Core System
SDM The error was produced by the SDM System

The resource can be one of the following:

Resource identifier Resource
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 /customer
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/prepaiment
79x /types/ideal
80x /types/giropay
81x /types/przelewy24
82x /types/eps
83x /types/pis
84x /types/invoice-secured
85x /types/bancontact
86x /types/installment-secured
87x /types/alipay
88x /types/applepay
89x /types/wechat
9xx not in use

Retrieve Error By ID

When merchant receives an error in response, merchant can get this error whenever time with private key.

This feature provides a convenient way for merchant to searching back the errors which happens in background.

curl -X GET https://api.unzer.com/v1/errors/p-err-85a6611365354a94ab55682d7c5  \
-u s-priv-xxxxxxxxxx:

returns:
{
  "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",
  } ]
}