Error handling

Error and debug information provided by Unzer API and SDK.

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 and logging all 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.

Error responses do not always have an HTTP error status code.
So, the response would have 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 an internal Unzer system.
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.

Error resource components

Error responses 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. The SDK throws a UnzerSDK\Exceptions\UnzerApiException whenever an error is returned by the API.

{
    "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, it could look like this: `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. 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.

Retrieving errors by ID

Fetching an error is not possible via PHP SDK. Please refer to Fetch error object of the Direct API integration documentation.

Handling server-side errors

When an error occurs, this causes an UnzerApiException that needs to be handled.

The exceptions are thrown in the following cases:

there is an error connecting to the API or to the payment core
there is an error executing a request

To identify the error, you should catch this exception and write it to your error log and show the clientMessage to your customer.

try {
$unzer = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');

$charge = new Charge(100.00, 'EUR', $returnUrl);
$unzer->performCharge($charge, $typeId);
} catch (UnzerApiException $e) {
    // write $e->getMerchantMessage(), $e->getErrorId() and $e->getCode() to your log
    // show $e->getClientMessage() on the client side if applicable
}

Runtime Exceptions

In some cases the SDK throws a RuntimeException. This is the case when there is an error using the SDK, such as the key has the wrong format or is not the private key or when a necessary resource does not exist.

We recommend you to catch those exceptions and handle them by writing them to your error log and showing a generic error message to the customer.

try {
    // your call to the api
} catch (\RuntimeException $ex) {
    //  write $ex->getMessage() to your error log
    //  redirect your customer to a failure page and show a generic message
}

Debug log

You can enable debug mode on your Unzer object in order to see the HTTP requests performed to the API and the raw responses. To use this functionality do the following:

Create your own debug handler class implementing the UnzerSDK\Interfaces\DebugHandlerInterface
Inject it into your Unzer object
Enable debug mode on your Unzer object

You can handle the message in the log method of your debug handler and write it into your debug log.


namespace Your\Namespace;
use UnzerSDK\Interfaces\DebugHandlerInterface;

class TestDebugHandler implements DebugHandlerInterface
{
    public function log ($message) {
        // write $message to your log
    }
}

$unzer = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');

$unzer->setDebugMode(true);
$unzer->setDebugHandler(new \Your\Namespace\TestDebugHandler());

Keeping a debug log can cause a significant amount of data over time. Make sure to disable debug mode when you finished debugging.

Verbose cURL output

To enable verbose curl output, you can set the environment variable UNZER_PAPI_CURL_VERBOSE to true.

Important information