.. index:: Error Handling

Error Handling
==============

In the Marktplaats API all calls are validated and if an error occurs a detailed
machine-readable error message is returned. Since some calls may return more
than one error for a given call, e.g. during the validation of a new ad, all
error responses contain lists of errors with one or more structured error
objects in them.

Each error contains a ``code`` and a ``message``, which provide an
error code and a simple error message in English. An error may contain a
``field`` attribute describing the field where the error occurred and an
additonal ``value`` attribute further specifying the error, i.e. the maximum
length of a field in case of a "string too long" error.

The validation will first check if the input parameters are of the correct type,
i.e. an integer should be an integer, not a string or a decimal value.
Secondly, the Marktplaats API will check if the provided input parameters are meaningful
within the context of the call. E.g. a category ID should be a positive integer.
Only the context specific checks are mentioned in the Errors section of the documentation page of
each call, as the type checks are considered generic.

.. code-block:: javascript

     HTTP/1.1 400 Bad Request
     Content-Type: application/json
     Content-Language: nl

     {
         "_links": {
             "help": {
               "href": "http://api.marktplaats.nl/v1/docs/errors/validation-failure"
             }
         },
         "logref": "4298asfpohsa98yasohq97q3yff22",
         "code" : "validation-failure",
         "message": "Validatie mislukt",
         "details": [
             { "field": "id",        "message": "Is not a valid number.",  "code": "not-a-number" },
             { "field": "name",      "message": "Minimum of 15 characters.", "code": "too-short", "value": "15" },
             { "field": "name",      "message": "'%' is not allowed","code": "pattern-did-not-match", "value": "[a-zA-Z0-9]{15,30}" },
             { "field": "shortName", "message": "Is not a car brand",     "code": "not-a-car-brand" },
             { "fields": ["field1", "field2"], "message": "Some error over multiple fields.", "code": "a-b-c" }
         ]
     }