Unzer

Error handling

Learn more about errors and how we communicate them.

Overview

Unzer API errors are returned in the JSON response and consist of a code, merchantMessage, and customerMessage. We recommend showing the customer message in the frontend of your customer and logging all the fields of unexpected errors for further investigation. You should also store the fields id and traceId that are useful when you need to find the root cause for an error. The id can also be used to fetch a specific error object later for analysis as described in the retrieving errors by ID section.

icon
Error responses do not always have an HTTP error status code. This means that the response would contain a 2XX HTTP status code that still has a list of errors in its payload.
{
  "id": "p-err-d0d2096c9bb04a2e8cecf776601",
  "isSuccess": false,
  "isPending": false,
  "isError": true,
  "url": "https://api.unzer.com/v1/customers",
  "timestamp": "2021-07-30 11:43:39",
  "traceId": "b7842b4951bc3752406e6e3f3c51a217",
  "errors": [
    {
      "code": "API.410.200.001",
      "merchantMessage": "lastName is missing",
      "customerMessage": "lastName is missing. Please contact us for more information."
    },
    {
      "code": "API.410.200.004",
      "merchantMessage": "firstName is missing.",
      "customerMessage": "firstName is missing. Please contact us for more information."
    }
  ]
}

HTTP response codes for errors

Code HTTP Response Possible causes
400 Bad Request Bad request to the API, for example, required parameter is missing or has an invalid syntax.
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 The requested resource does not exist.
405 Method Not Allowed The chosen payment type is not configured for the merchant or the HTTP method can not be used for the requested resource.
415 Unsupported media type The request media type is not supported by the system.
500 Internal Server Error An error occurred in a subsequent system:Payment API, Payment Core, SDM, Partner System, and so on.
504 Gateway Timeout The server did not receive a fast enough response from another server upstream when it attempted to load one of the web pages.

Unzer Error components

Error responses contain the information about the origin of the error in the form of a JSON object. Within the error object, there is a list of errors specifying all the possible problems in a chunk.

{
  "code": "API.410.200.004",
  "merchantMessage": "firstName is missing.",
  "customerMessage": "firstName is missing. Please contact us for more information."
}
Key Description
code Uniquely identifies the error, for example API.410.200.004.
merchantMessage Specifies the error details 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 Specifies the message to be displayed to your customer. It is available in several languages, based on the Accept Language header.

To learn more about how to set the language for the error messages, see Localization and languages.

Retrieving errors by ID

You can retrieve each error object you received in the past, by using its unique ID. To learn more, see Fetch error object

Handling server-side errors

Log the errors, the error object ID etc. and show the `customerMessage` to the client, if applicable.
try {
    $unzer = new Unzer(UNZER_PAPI_PRIVATE_KEY);
    $transaction = $unzer->charge(119.0, 'EUR', $paymentTypeId, 'https://your.return.url');
} catch (UnzerApiException $e) {
    // write $e->getMerchantMessage(), $e->getErrorId() and $e->getCode() to your log
    // show $e->getClientMessage() on the client side if applicable
}
try {
    charge = sepa.charge(new BigDecimal(119.0), Currency.getInstance("EUR"), new URL("https://your.return.url"));
} catch (PaymentException e) {
    // write the error information from the PaymentExceptions field paymentErrorList to your log
    // show the field customerMessage from the paymentErrors on the client side if applicable
}

See also

Notifications