Skip to content

Error Responses

Problem Detail Update

Since release 2.18.0, the API supports two error response formats: a new ApiProblemDetail which follows the problem detail standard proposed in RFC 9457, and the legacy ApiError format for backward compatibility. The problem detail standard provides more structured error information, making it easier to handle errors programmatically and debug issues. To receive the new ApiProblemDetail response, set your Accept header to: application/json, application/problem+json. For backward compatibility, the API continues to return the legacy ApiError format when the Accept header is set to: application/json. This dual-format support allows you to migrate your error handling to the new format if you want while ensuring existing integrations continue to work as expected.

HTTP Status Codes

If an error occurs when handling the API, you will receive an HTTP status code greater than or equal to 400. MDN provides detailed information about each status code.

A basic distinction is made between two types of errors:

  • Client errors (400-499): There are issues with your request that require correction.
  • Server errors (500-599): There is an issue with our server. If this occurs persistently, please contact our support

Response Format Details

To further isolate an error, the API provides detailed error information in the response body. The format of the response will differ based on your accept header.

Problem Detail Format

Accept Header: application/json, application/problem+json

Response Fields

  • status: The HTTP status code
  • type: A relative URI the uniquely identifies the problem type
  • title: A short summary of the problem
  • detail: An optional extended summary of the problem(not always included)
  • timestamp: An ISO-8601 formatted timestamp of when the error occurred
  • instance: A relative URI of the request that caused the error

Example Response

{
  "status": 400,
  "type": "/problems/geocoder/missing-address",
  "title": "An address string has to be provided",
  "timestamp": "2024-12-06T10:53:41.131701906Z",
  "instance": "/v1/geocoder?provider=TomTom&address=%20&country=DEU&limit=1"
}

The type field is unique and stable, making it useful for troubleshooting in your application. For requests that have multiple errors, the detail field will include error messages separated by semicolons. See the example with multiple constraint violations below.

Legacy ApiError Format

Accept Header: application/json

Response Fields

  • status: The HTTP status code
  • details: An array containing a unique code and message for each error
  • errors: An array of error descriptions (deprecated since version 2.12, replaced by details)

Example Response

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

Multiple Errors

While most requests return a single error (the first one encountered), responses may contain multiple errors when several constraints are violated simultaneously. Each error has a unique, stable code for programmatic handling and a human-readable message that may include specific constraint values. See the Route with multiple constraint violations example.

Error Examples

Optimization Request with Region Size Constraint

Here is a request is for an optimized route between New York, Paris, and Berlin which exceeds the maximum allowed region size:

curl -X 'POST' \
  'https://api.maptrip.de/v1/optimize/stops?provider=TomTom&startTime=2021-07-06T17%3A02%3A00%2B02%3A00' \
  -H 'accept: application/json, application/problem+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
  }
]

Response Formats:

accept: application/json, application/problem+json

{
  "status": 413,
  "type": "/problems/optimize/diameter-too-large",
  "title": "The region in which the stops are located is too large",
  "detail":"The region in which the stops are located must not exceed 1200 km in diameter",
  "timestamp": "2024-12-06T10:53:41.131701906Z",
  "instance": "v1/optimize/stops?provider=TomTom&startTime=2021-07-06T17%3A02%3A00%2B02%3A00"
}

accept: application/json

{
  "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"
    }
  ]
}

Common Error Scenarios:

Geocoding Request with Empty Address

accept: application/json, application/problem+json

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

{
  "status": 400,
  "type": "/problems/geocoder/missing-address",
  "title": "An address string has to be provided",
  "timestamp": "2024-12-06T10:53:41.131701906Z",
  "instance": "/v1/geocoder?provider=TomTom&address=%20&country=DEU&limit=1"
}

accept: application/json

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 Request with Invalid Filename

accept: application/json

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

{
  "status": 400,
  "type": "/problems/detour/invalid-filename",
  "title": "File name is invalid",
  "timestamp": "2024-12-06T10:53:41.131701906Z",
  "instance": "/v1/detour/file?provider=TomTom"
}

accept: application/json

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 Request with Multiple Constraint Violations

accept: application/json

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, application/problem+json" -H "Authorization: Bearer <token>"

{
  "status":400,
  "type":"/problems/general/invalid-parameter/",
  "title":"Some of your parameters have invalid values",
  "detail":"alternatives: must be less than or equal to 2; emergencyRoutingRadius: must be less than or equal to 5000",
  "timestamp":"2024-12-06T14:23:35.581606Z",
  "instance":"/v1/route?provider=TomTom&from=50.73270%2C7.09630&to=50.94212%2C6.95781&vehicle=car&type=fastest&alternatives=10&emergencyRoutingRadius=50000"
}

accept: application/json

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"
    }
  ]
}