Errors

HTTP status codes

Whenever you send a request to the Mollie API you'll get a response in JSON (JavaScript Object Notation) format. This is a standard for data communication that's easy to read for humans as well as machines. Alongside the JSON-response an HTTP status code is sent that shows whether the request was successful or not. If it wasn't, you can tell by the code and the message in the JSON-response what went wrong, why it went wrong and whether there is something you can do about it.

A successful request

An HTTP status 200 OK is issued whenever your request was a success. You see this type of response in our examples like this one below where we successfully retrieve a payment.

Request code

require_once 'Mollie/API/Autoloader.php';

$mollie = new Mollie_API_Client;
$mollie->setApiKey('test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM');

$payment_id = 'tr_WDqYK6vllg';
$payment    = $mollie->payments->get($payment_id);

/*
 * The order ID saved in the payment can be used to load the order and update it's
 * status
 */
$order_id = $payment->metadata->order_id;

if ($payment->isPaid())
{
    /*
     * At this point you'd probably want to start the process of delivering the product
     * to the customer.
     */
}
elseif (! $payment->isOpen())
{
    /*
     * The payment isn't paid and isn't open anymore. We can assume it was aborted.
     */
}

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "resource": "payment",
    "id": "tr_WDqYK6vllg",
    "mode": "test",
    "createdDatetime": "2017-12-16T17:27:06.0Z",
    "status": "paid",
    "paidDatetime": "2017-12-16T17:31:49.0Z",
    "amount": "35.07",
    "description": "Order 33",
    "method": "ideal",
    "metadata": {
        "order_id": "33"
    },
    "details": {
        "consumerName": "Hr E G H K\u00fcppers en\/of MW M.J. K\u00fcppers-Veeneman",
        "consumerAccount": "NL53INGB0618365937",
        "consumerBic": "INGBNL2A"
    },
    "locale": "nl",
    "profileId": "pfl_QkEhN94Ba",
    "links": {
        "webhookUrl": "https://webshop.example.org/payments/webhook",
        "redirectUrl": "https://webshop.example.org/order/33/"
    }
}

Examples of error responses

Things will sometimes go wrong. For instance when a request is made with the wrong API key, this error will be the result:

Request code

require_once 'Mollie/API/Autoloader.php';

$mollie = new Mollie_API_Client;
$mollie->setApiKey('test_deliberately_invalid_key');

$payment_id = 'tr_WDqYK6vllg';

try
{
    $payment = $mollie->payments->get($payment_id);
}
catch (Mollie_API_Exception $e)
{
    /* 
     * This is where you output the 401 error 
     */
     echo "API call failed: " . htmlspecialchars($e->getMessage());
}

Response

HTTP/1.1 401 Authorization Required
Content-Type: application/json; charset=utf-8

{
    "error": {
        "type": "request",
        "message": "Unauthorized request",
        "links": {
            "documentation": "/be-fr/developers"
        }
    }
}

The HTTP status 401 Authorization Required indicates missing or incorrect authorization to execute the desired action.

Another error that occurs often, is the well known HTTP status 404 Not Found, which indicates the object you're trying to manipulate does not exist:

Request code

require_once 'Mollie/API/Autoloader.php';

$mollie = new Mollie_API_Client;
$mollie->setApiKey('test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM');

$payment_id = 'tr_I_dont_exist';

try
{
    $payment = $mollie->payments->get($payment_id);
}
catch (Mollie_API_Exception $e)
{
    /* 
     * This is where you output the 404 error
     */
     echo "API call failed: " . htmlspecialchars($e->getMessage());
}

Response

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
    "error": {
        "type": "request",
        "message": "The payment id is invalid"
    }
}

Sometimes a status 422 Unprocessable Entity is thrown. When it occurs there is extra information in the JSON about what part or field of your request is likely to be causing the error. In these cases you'll find the response has the parameter field. In the example below we deliberately used an amount that was too low:

Request code

require_once 'Mollie/API/Autoloader.php';

$mollie = new Mollie_API_Client;
$mollie->setApiKey('test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM');

try
{
    $payment = $mollie->payments->create(
        array(
            'amount'      => 0.01,
            'description' => 'My first payment',
            'redirectUrl' => 'https://webshop.example.org/order/12345/',
            'webhookUrl'  => 'https://webshop.example.org/payments/webhook/',
            'metadata'    => array(
                'order_id' => '12345'
            )
        )
    );

    /*
     * Send the customer off to complete the payment.
     */
    header("Location: " . $payment->getPaymentUrl());
    exit;
}
catch (Mollie_API_Exception $e)
{
    echo "API call failed: " . htmlspecialchars($e->getMessage());
    echo " on field " . htmlspecialchars($e->getField());
}

Response

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json; charset=utf-8

{
    "error": {
        "type": "request",
        "message": "The amount is lower than the minimum",
        "field": "amount"
    }
}

All error types listed

The first digit of the status code indicates the type or class of the status. Using this first digit you can determine the best approach for dealing with an error. The following classes of codes are relevant to the Mollie API:

  • A code in the 2xx range comes with a Mollie API response indicating success.
  • A code in the 4xx range is an error code returned from the Mollie API where the client (your responsibility) seems to be causing the error. Whenever this happens you can change your code to prevent the error from happening again. The error for this specific request usually won't go away by itself.
  • A code in the 5xx range is an error caused by the server (Mollie's responsibility). So caused by the Mollie API or it's infrastructure. In the rare case you get this type of error, something is wrong with the Mollie API. The errors should subside without your mediation.

All possible status codes

The Mollie API will only ever return a subset of all legal HTTP status codes. Here's the full list:

200

OK – Your request was successful.

201

Created – The entity was created successfully.

204

No Content – The requested entity no longer exists.

400

Bad Request – The Mollie API was unable to understand your request. There might be an error in your syntax.

401

Unauthorized – Your request wasn't executed due to failed authentication. Check your API key.

403

Forbidden – You do not have access to the requested resource, for example if you're trying to create a payment for payment method that you did not activate yet.

404

Not Found – The object referenced by your URL does not exist.

405

Method Not Allowed – You're trying to use an HTTP method that is not applicable on this URL or resource. Refer to the Allow header to see which methods the endpoint supports.

415

Unsupported Media Type – Your request's encoding is not supported or is incorrectly understood. Please always use UTF-8.

422

Unprocessable Entity – We could not process your request due to another reason than the ones listed above. Please contact us for more details.

429

Too Many Requests – Your request has hit a rate limit. Please wait for a bit and retry.

500

Internal Server Error – An internal server error occurred while processing your request. Our developers are notified automatically, but if you have any information on how you triggered the problem, please contact us.

502

Bad Gateway – The service is temporarily unavailable, either due to calamity or (planned) maintenance. Please retry the request at a later time.

503

Service Unavailable – The service is temporarily unavailable, either due to calamity or (planned) maintenance. Please retry the request at a later time.

504

Gateway Timeout – Your request is causing an unusually long process time.