Handling errors

Errors may occur when handling the API. If an error occurs, you will receive an HTTP status code greater than or equal to 400. In this case, MDN will give you information about the cause.

A basic distinction is made between two types of errors:

• an error between 400 and 499 is a client error. In this case you must correct your request
• an error between 500 and 599 is a server error. If this occurs persistently, please contact our support

To further isolate an error, the API provides a response object that looks like this:

{
  "status": 400,
  "errors": ["An address string has to be provided"],
  "details": [
    {
      "code": "GEOCODER_ERROR_MISSING_ADDRESS",
      "message": "An address string has to be provided"
    }
  ]
}

This includes the following properties:

• status: The HTTP status code
• details: An array containing a unique code and message for each error that occurred.
• errors: An array with descriptions of each error. This will be replaced by details from version 2.12 and is deprecated.

Note: Both details and messages may contain multiple errors. Normally you will receive exactly one error (the first one that occurred for your request), but in some cases you will receive several notices at once. An example would be a routing request that contains both 10 alternative routes and an emergency radius of 50 km.

The code is unique and will not change. You can use it to identify and troubleshoot specific errors in your software. The message gives you a more understandable description and can contain more details. For example, in this example the maximum diameter for the area in which an optimization is carried out is stated.

Here is an example which triggers an error. The request is for an optimized route between New York, Paris, and Berlin. The response has a response of 413 with a details message that says, "The region in which the stops are located must not exceed 1200 km in diameter."

curl -X 'POST' \
  'https://api.maptrip.de/v1/optimize/stops?provider=TomTom&startTime=2021-07-06T17%3A02%3A00%2B02%3A00' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '[
  {
    "name": "Times Square, New York City",
    "coordinate": {
      "lat": 40.758896,
      "lon": -73.985130
    },
    "start": true,
    "destination": false
  },
  {
    "name": "Eiffel Tower, Paris",
    "coordinate": {
      "lat": 48.858372,
      "lon": 2.294481
    },
    "start": false,
    "destination": false
  },
  {
    "name": "Brandenburg Gate, Berlin",
    "coordinate": {
       "lat": 52.516282,
       "lon": 13.379482
    },
    "start": false,
    "destination": true
  }
]

{
  "status": 413,
  "errors": [
    "The region in which the stops are located must not exceed 1200 km in diameter"
  ],
  "details": [
    {
      "code": "OPTIMIZE_ERROR_DIAMETER_TOO_LARGE",
      "message": "The region in which the stops are located must not exceed 1200 km in diameter"
    }
  ]
}

More examples of common requests which return errors from the API:

• Geocoding with empty address

curl -v "https://stagingapi.maptrip.de/v1/geocoder?provider=TomTom&address=%20&country=DEU&limit=1" -H "accept: application/json" -H "Authorization: Bearer <token>"

{
  "status": 400,
  "errors": ["An address string has to be provided"],
  "details": [
    {
      "code": "GEOCODER_ERROR_MISSING_ADDRESS",
      "message": "An address string has to be provided"
    }
  ]
}

• Detour with invalid filename

curl -X "POST" "https://stagingapi.maptrip.de/v1/detour/file?provider=TomTom" -H "accept: application/json" -H "Authorization: Bearer <token>" -H "Content-Type: text/plain" -d "a"

{
  "status": 400,
  "errors": ["File name is invalid"],
  "details": [
    {
      "code": "DETOUR_ERROR_INVALID_FILENAME",
      "message": "File name is invalid"
    }
  ]
}

• Route with multiple constraint violations

curl "https://stagingapi.maptrip.de/v1/route?provider=TomTom&from=50.73270%2C7.09630&to=50.94212%2C6.95781&vehicle=car&type=fastest&alternatives=10&emergencyRoutingRadius=50000" -H "accept: application/json" -H "Authorization: Bearer <token>"

{
  "status": 400,
  "errors": [
    "emergencyRoutingRadius must be less than or equal to 5000",
    "alternatives must be less than or equal to 2"
  ],
  "details": [
    {
      "code": "ERROR_INVALID_PARAMETER",
      "message": "emergencyRoutingRadius must be less than or equal to 5000"
    },
    {
      "code": "ERROR_INVALID_PARAMETER",
      "message": "alternatives must be less than or equal to 2"
    }
  ]
}