Asynchronous Batch Submission

Service version: 2
Last edit: 2022.09.26

Purpose

This endpoint allows the submission of a new batch for asynchronous processing. It responds with a redirect to the location at which the batch results can be obtained when the batch processing has completed.

Request data

HTTPS method: POST

For ease of viewing and identification:

  • Constants and parameters enclosed in curly brackets &#123 } must be replaced with their values.
  • Please see the following Request parameters section with the required and optional parameters tables for their values. The generic request format is as follows.

URL request format

https://{baseURL}/search/{versionNumber}/batch.{outputFormat}?key={Your_API_Key}&redirectMode={redirectMode}&waitTimeSeconds={waitTimeSeconds}

URL request example

https://api.tomtom.com/search/2/batch.json?key={Your_API_Key}

curl command request format

1curl -X POST 'curl -XPOST -d '{
2 "batchItems": [
3 {"query": "/search/lodz.json?limit=10&idxSet=POI,PAD,Str,Xstr,Geo,Addr"},
4 {"query": "/search/wroclaw.json?limit=10&idxSet=POI,PAD,Str,Xstr,Geo,Addr"},
5 {"query": "/search/berlin.json?limit=10&idxSet=POI,PAD,Str,Xstr,Geo,Addr"}
6 ]
7}' 'https://api.tomtom.com/search/2/batch.json?key={Your_API_Key}'

Request parameters

The following table describes the request parameters.

  • Required parameters must be used or the call will fail.
  • Optional parameters may be used.
  • The order of request parameters is not important.

Required parameters

Description

baseURL
string

Base URL for calling the API.


Values:
versionNumber
string

Service version.


Value: The current value is 2.

key
string

An API Key valid for the requested service.


Value: Your valid API Key.

outputFormat
string

The content type of the response structure.


Values: json and xml

Optional parameters

Description

redirectMode
string

Controls the HTTP code of the successful HTTP response to the submission request. When set to auto, HTTP code 303 is returned. The HTTP client may automatically redirect to the Download endpoint. When set to manual, HTTP code 202 is returned. The HTTP client will not automatically redirect to the Download endpoint. In both cases the same Location header is included.


Default value: auto
Other value: manual
waitTimeSeconds
integer

Allows changing the maximum amount of time, in seconds, for which the client may have to wait for an Asynchronous Batch Download response while the batch is being processed. Please note that the provided waitTimeSeconds

parameter and its value are passed to the Location response header as a part of the URI.


Default value: 120

Other values: It may be either 5..60 or 120.

Request headers

The following data table describes HTTP request headers of particular interest to Batch Search service clients. Required headers must be used or the call will fail. Optional headers may be used.

Required headers

Description

Content-Type

Specifies the MIME type of the body of the request.


Values: application/xml and application/json.

Optional headers

Description

Tracking-ID

Specifies an identifier for the request. It can be used to trace a call. The value must match the regular expression '^[a-zA-Z0-9-]{1,100}$'. An example of format that matches this regular expression is UUID: (e.g., 9ac68072-c7a4-11e8-a8d5-f2801f1b9fd1). For details check

RFC 4122

. If specified, it is replicated in the Tracking-ID response header. It is only meant to be used for support and does not involve tracking of you or your users in any form.


Value: An identifier for the request.

Supported Search API suite endpoints

A list of Search API suite endpoints supported by the Batch Search service can be found below. For details regarding particular API usage, consult the following respective API documentation pages:

Other API endpoints support

POST body

The POST body of a batch request should contain a set of items which will be used to execute requests to supported endpoints of the Search API suite. Each batch request can contain items corresponding to multiple supported endpoints of the Search API suite. For each endpoint, the same body structure applies and specific parameters of each endpoint are expected to go into query elements.

1<?xml version="1.0" encoding="utf-8"?>
2<batchRequest>
3 <batchItems>
4 <batchItem>
5 <query>...</query>
6 </batchItem>
7 ...
8 <batchItem>
9 <query>...</query>
10 <post>...</post>
11 </batchItem>
12 </batchItems>
13</batchRequest>
1{
2 "batchItems": [
3 {"query": "..."},
4 ...
5 {
6 "query": "...",
7 "post": {...}
8 }
9 ]
10}

POST body fields

Field

Description

batchRequestRoot element of the request.
batchItems

A set of batch items. The maximum number of batch items for an Asynchronous API is 10000.

batchItemA single batch item.
query

A string used to build a request to one of the supported endpoints of the

Search API

suite. It is a partial URL without protocol, base URL, service version, and API Key. The output format must match the

outputFormat

parameter of the batch request. If a batch contains any

Additional Data

service item, the

outputFormat

parameter value must be set to json as the Additional Data service does not support the XML response format.



A query must be properly URL-encoded. For example, a Fuzzy Search query "Lodz, Mochnackiego 15/19" should be written as follows (XML format):

<query>/search/Lodz%2C%20Mochnackiego%2015%2F19</query>

. A sample online URL encoder can be found at: URL Encoder.


When posting XML to the Batch Search service, the &lt;query&gt; element values must be valid XML (e.g., the "&" character must be replaced by the predefined XML entity "&amp;"). More information is in the List of XML character entity references. When posting JSON to the Batch Search service, the &lt;query&gt; string values must be properly escaped; e.g., the " character should be escaped with a \ (backslash). More information is available in

RFC 7159

.

post


Contains data that is sent to the

Geometry Search

or

Along Route Search

services using the HTTP POST method. These services accept POST data only in JSON format. For batch submissions in XML format, the <post> element's value must also be an appropriate JSON object. A JSON object provided in the XML <post> element must be valid XML, i.e., it has to be properly XML escaped or wrapped in a

CDATA section

if necessary.

POST body examples

Mixed endpoint examples
1<?xml version="1.0" encoding="utf-8"?>
2<batchRequest>
3 <batchItems>
4 <batchItem>
5 <query>/poiSearch/rembrandt museum.xml</query>
6 </batchItem>
7 <batchItem>
8 <query>/geometrySearch/restaurant.xml?geometryList=[{"type":"CIRCLE","position":"51.5123443,-0.0909851","radius":1000}]</query>
9 </batchItem>
10 <batchItem>
11 <query>/geometrySearch/pizza.xml</query>
12 <post>
13 {
14 "geometryList":[
15 {
16 "type": "CIRCLE",
17 "position": "51.5123443,-0.0909851",
18 "radius": 1000
19 }
20 ]
21 }
22 </post>
23 </batchItem>
24 <batchItem>
25 <query>/searchAlongRoute/restaurant.xml?maxDetourTime=300</query>
26 <post>
27 {
28 "route": {
29 "points": [
30 {
31 "lat": 37.7524152343544,
32 "lon": -122.43576049804686
33 },
34 {
35 "lat": 37.70660472542312,
36 "lon": -122.43301391601562
37 },
38 {
39 "lat": 37.712059855877314,
40 "lon": -122.36434936523438
41 },
42 {
43 "lat": 37.75350561243041,
44 "lon": -122.37396240234374
45 }
46 ]
47 }
48 }
49 </post>
50 </batchItem>
51 <batchItem>
52 <query>/reverseGeocode/crossStreet/52.4781801,4.8884868.xml</query>
53 </batchItem>
54 <batchItem>
55 <query>/search/lodz.xml?limit=10&amp;idxSet=POI,PAD,Str,Xstr,Geo,Addr</query>
56 </batchItem>
57 </batchItems>
58</batchRequest>
1{
2 "batchItems": [
3 { "query": "/poiSearch/rembrandt museum.json" },
4 {
5 "query": "/geometrySearch/parking.json?geometryList=[{\"type\":\"CIRCLE\",\"position\":\"51.5123443,-0.0909851\",\"radius\":1000}]"
6 },
7 {
8 "query": "/geometrySearch/pizza.json",
9 "post": {
10 "geometryList": [
11 {
12 "type": "CIRCLE",
13 "position": "51.5123443,-0.0909851",
14 "radius": 1000
15 }
16 ]
17 }
18 },
19 {
20 "query": "/searchAlongRoute/restaurant.json?maxDetourTime=300",
21 "post": {
22 "route": {
23 "points": [
24 {
25 "lat": 37.7524152,
26 "lon": -122.4357604
27 },
28 {
29 "lat": 37.7066047,
30 "lon": -122.4330139
31 },
32 {
33 "lat": 37.7120598,
34 "lon": -122.3643493
35 },
36 {
37 "lat": 37.7535056,
38 "lon": -122.3739624
39 }
40 ]
41 }
42 }
43 },
44 { "query": "/reverseGeocode/crossStreet/52.4829893,4.9247074.json" },
45 {
46 "query": "/search/lodz.json?limit=10&idxSet=POI,PAD,Str,Xstr,Geo,Addr&maxFuzzyLevel=2"
47 }
48 ]
49}
Fuzzy Search examples
1<?xml version="1.0" encoding="utf-8"?>
2<batchRequest>
3 <batchItems>
4 <batchItem>
5 <query>/search/lodz.xml?limit=10&amp;idxSet=POI,PAD,Str,Xstr,Geo,Addr</query>
6 </batchItem>
7 <batchItem>
8 <query>/search/wroclaw.xml?limit=10&amp;idxSet=POI,PAD,Str,Xstr,Geo,Addr</query>
9 </batchItem>
10 <batchItem>
11 <query>/search/berlin.xml?limit=10&amp;idxSet=POI,PAD,Str,Xstr,Geo,Addr</query>
12 </batchItem>
13 </batchItems>
14</batchRequest>
1{
2 "batchItems": [
3 { "query": "/search/lodz.json?limit=10&idxSet=POI,PAD,Str,Xstr,Geo,Addr" },
4 {
5 "query": "/search/wroclaw.json?limit=10&idxSet=POI,PAD,Str,Xstr,Geo,Addr"
6 },
7 { "query": "/search/berlin.json?limit=10&idxSet=POI,PAD,Str,Xstr,Geo,Addr" }
8 ]
9}
POI Search examples
1<?xml version="1.0" encoding="utf-8"?>
2<batchRequest>
3 <batchItems>
4 <batchItem>
5 <query>/poiSearch/rembrandt museum.xml</query>
6 </batchItem>
7 <batchItem>
8 <query>/poiSearch/big ben.xml</query>
9 </batchItem>
10 <batchItem>
11 <query>/poiSearch/colosseo.xml</query>
12 </batchItem>
13 </batchItems>
14</batchRequest>
1{
2 "batchItems": [
3 { "query": "/poiSearch/rembrandt museum.json" },
4 { "query": "/poiSearch/big ben.json" },
5 { "query": "/poiSearch/colosseo.json" }
6 ]
7}
Category Search examples
1<?xml version="1.0" encoding="utf-8"?>
2<batchRequest>
3 <batchItems>
4 <batchItem>
5 <query>/categorySearch/airport.xml?lat=52.229404&amp;lon=21.011422</query>
6 </batchItem>
7 <batchItem>
8 <query>/categorySearch/restaurant.xml?lat=38.925518&amp;lon=76.990957</query>
9 </batchItem>
10 <batchItem>
11 <query>/categorySearch/hotel.xml?lat=34.016308&amp;lon=-118.277123</query>
12 </batchItem>
13 </batchItems>
14</batchRequest>
1{
2 "batchItems": [
3 { "query": "/categorySearch/airport.json?lat=52.229404&lon=21.011422" },
4 { "query": "/categorySearch/restaurant.json?lat=38.925518&lon=76.990957" },
5 { "query": "/categorySearch/hotel.json?lat=34.016308&lon=-118.277123" }
6 ]
7}
Geometry Search examples
1<?xml version="1.0" encoding="utf-8"?>
2<batchRequest>
3 <batchItems>
4 <batchItem>
5 <query>/geometrySearch/restaurant.xml?geometryList=[{"type":"CIRCLE","position":"51.5123443,-0.0909851","radius":1000}]</query>
6 </batchItem>
7 <batchItem>
8 <query>/geometrySearch/pizza.xml</query>
9 <post>
10 {
11 "geometryList":[
12 {
13 "type": "CIRCLE",
14 "position": "51.5123443,-0.0909851",
15 "radius": 1000
16 }
17 ]
18 }
19 </post>
20 </batchItem>
21 </batchItems>
22</batchRequest>
1{
2 "batchItems": [
3 {
4 "query": "/geometrySearch/parking.json?geometryList=[{\"type\":\"CIRCLE\",\"position\":\"51.5123443,-0.0909851\",\"radius\":1000}]"
5 },
6 {
7 "query": "/geometrySearch/pizza.json",
8 "post": {
9 "geometryList": [
10 {
11 "type": "CIRCLE",
12 "position": "51.5123443,-0.0909851",
13 "radius": 1000
14 }
15 ]
16 }
17 }
18 ]
19}
Nearby Search examples
1<?xml version="1.0" encoding="utf-8"?>
2<batchRequest>
3 <batchItems>
4 <batchItem>
5 <query>/nearbySearch/.xml?lat=40.702594&amp;lon=-74.045358&amp;radius=2000</query>
6 </batchItem>
7 <batchItem>
8 <query>/nearbySearch/.xml?lat=41.774831&amp;lon=-87.771554&amp;radius=2000</query>
9 </batchItem>
10 <batchItem>
11 <query>/nearbySearch/.xml?lat=48.141307&amp;lon=17.117647&amp;radius=2000</query>
12 </batchItem>
13 </batchItems>
14</batchRequest>
1{
2 "batchItems": [
3 { "query": "/nearbySearch/.json?lat=40.702594&lon=-74.045358&radius=2000" },
4 { "query": "/nearbySearch/.json?lat=41.774831&lon=-87.771554&radius=2000" },
5 { "query": "/nearbySearch/.json?lat=48.141307&lon=17.117647&radius=2000" }
6 ]
7}
Along Route Search examples
1<?xml version="1.0" encoding="utf-8"?>
2<batchRequest>
3 <batchItems>
4 <batchItem>
5 <query>/searchAlongRoute/restaurant.xml?maxDetourTime=300</query>
6 <post>
7 {
8 "route": {
9 "points": [
10 {
11 "lat": 37.7524152343544,
12 "lon": -122.43576049804686
13 },
14 {
15 "lat": 37.70660472542312,
16 "lon": -122.43301391601562
17 },
18 {
19 "lat": 37.712059855877314,
20 "lon": -122.36434936523438
21 },
22 {
23 "lat": 37.75350561243041,
24 "lon": -122.37396240234374
25 }
26 ]
27 }
28 }
29 </post>
30 </batchItem>
31 <batchItem>
32 <query>/searchAlongRoute/restaurant.xml?maxDetourTime=300</query>
33 <post>
34 {
35 "route": {
36 "points": [
37 {
38 "lat": 48.19871,
39 "lon": 16.36319
40 },
41 {
42 "lat": 48.19843,
43 "lon": 16.36262
44 },
45 {
46 "lat": 48.19824,
47 "lon": 16.36226
48 },
49 {
50 "lat": 48.19788,
51 "lon": 16.3615
52 }
53 ]
54 }
55 }
56 </post>
57 </batchItem>
58 </batchItems>
59</batchRequest>
1{
2 "batchItems": [
3 {
4 "query": "/searchAlongRoute/restaurant.json?maxDetourTime=300",
5 "post": {
6 "route": {
7 "points": [
8 {
9 "lat": 37.7524152,
10 "lon": -122.4357604
11 },
12 {
13 "lat": 37.7066047,
14 "lon": -122.4330139
15 },
16 {
17 "lat": 37.7120598,
18 "lon": -122.3643493
19 },
20 {
21 "lat": 37.7535056,
22 "lon": -122.3739624
23 }
24 ]
25 }
26 }
27 },
28 {
29 "query": "/searchAlongRoute/restaurant.json?maxDetourTime=300",
30 "post": {
31 "route": {
32 "points": [
33 {
34 "lat": 48.19871,
35 "lon": 16.36319
36 },
37 {
38 "lat": 48.19843,
39 "lon": 16.36262
40 },
41 {
42 "lat": 48.19824,
43 "lon": 16.36226
44 },
45 {
46 "lat": 48.19788,
47 "lon": 16.3615
48 }
49 ]
50 }
51 }
52 }
53 ]
54}
Geocode Search examples
1<?xml version="1.0" encoding="utf-8"?>
2<batchRequest>
3 <batchItems>
4 <batchItem>
5 <query>/geocode/tower bridge.xml</query>
6 </batchItem>
7 <batchItem>
8 <query>/geocode/new york.xml</query>
9 </batchItem>
10 <batchItem>
11 <query>/geocode/amsterdam.xml</query>
12 </batchItem>
13 </batchItems>
14</batchRequest>
1{
2 "batchItems": [
3 { "query": "/geocode/tower bridge.json" },
4 { "query": "/geocode/new york.json" },
5 { "query": "/geocode/amsterdam.json" }
6 ]
7}
Structured Geocode examples
1<?xml version="1.0" encoding="utf-8"?>
2<batchRequest>
3 <batchItems>
4 <batchItem>
5 <query>/structuredGeocode.xml?countryCode=FR&amp;municipality=Paris&amp;streetName=Avenue de Suffren&amp;streetNumber=70</query>
6 </batchItem>
7 <batchItem>
8 <query>/structuredGeocode.xml?countryCode=ES&amp;municipality=Madrid&amp;streetName=Calle Mariblanca&amp;streetNumber=25</query>
9 </batchItem>
10 </batchItems>
11</batchRequest>
1{
2 "batchItems": [
3 {
4 "query": "/structuredGeocode.json?countryCode=FR&municipality=Paris&streetName=Avenue de Suffren&streetNumber=70"
5 },
6 {
7 "query": "/structuredGeocode.json?countryCode=ES&municipality=Madrid&streetName=Calle Mariblanca&streetNumber=25"
8 }
9 ]
10}
Reverse Geocode examples
1<?xml version="1.0" encoding="utf-8"?>
2<batchRequest>
3 <batchItems>
4 <batchItem>
5 <query>/reverseGeocode/48.203233,16.360454.xml</query>
6 </batchItem>
7 <batchItem>
8 <query>/reverseGeocode/-26.202878,28.033040.xml</query>
9 </batchItem>
10 <batchItem>
11 <query>/reverseGeocode/12.975469,77.597284.xml</query>
12 </batchItem>
13 </batchItems>
14</batchRequest>
1{
2 "batchItems": [
3 { "query": "/reverseGeocode/48.203233,16.360454.json" },
4 { "query": "/reverseGeocode/-26.202878,28.033040.json" },
5 { "query": "/reverseGeocode/12.975469,77.597284.json" }
6 ]
7}
CrossStreet lookup examples
1<?xml version="1.0" encoding="utf-8"?>
2<batchRequest>
3 <batchItems>
4 <batchItem>
5 <query>/reverseGeocode/crossStreet/52.4781801,4.8884868.xml</query>
6 </batchItem>
7 <batchItem>
8 <query>/reverseGeocode/crossStreet/12.977194,77.608367.xml</query>
9 </batchItem>
10 <batchItem>
11 <query>/reverseGeocode/crossStreet/21.130272,79.063060.xml</query>
12 </batchItem>
13 </batchItems>
14</batchRequest>
1{
2 "batchItems": [
3 { "query": "/reverseGeocode/crossStreet/52.4781801,4.8884868.json" },
4 { "query": "/reverseGeocode/crossStreet/12.977194,77.608367.json" },
5 { "query": "/reverseGeocode/crossStreet/21.130272,79.063060.json" }
6 ]
7}
Additional Data examples
1<?xml version="1.0" encoding="utf-8"?>
2<batchRequest>
3 <batchItems>
4 <batchItem>
5 <query>/additionalData.json?geometries=00004631-3400-3c00-0000-0000673c4d2e</query>
6 </batchItem>
7 <batchItem>
8 <query>/additionalData.json?geometries=00004631-3400-3c00-0000-0000673c42fe</query>
9 </batchItem>
10 </batchItems>
11</batchRequest>

The preceding POST body contains example geometry ID values. Proper geometry ID values can be retrieved from a Search request.

1{
2 "batchItems": [
3 {
4 "query": "/additionalData.json?geometries=00004631-3400-3c00-0000-0000673c4d2e"
5 },
6 {
7 "query": "/additionalData.json?geometries=00004631-3400-3c00-0000-0000673c42fe"
8 }
9 ]
10}

The preceding POST body contains example geometry ID values. Proper geometry ID values can be retrieved from a Search request.

EV Charging Stations Availability examples
1<?xml version="1.0" encoding="utf-8"?>
2<batchRequest>
3 <batchItems>
4 <batchItem>
5 <query>/chargingAvailability.xml?chargingAvailability=00112233-4455-6677-8899-aabbccddeeff</query>
6 </batchItem>
7 <batchItem>
8 <query>/chargingAvailability.xml?chargingAvailability=00112233-4455-6677-8899-001122334455</query>
9 </batchItem>
10 </batchItems>
11</batchRequest>

The preceding POST body contains example charging availability ID values. Proper charging availability ID values can be retrieved from a Search request.

1{
2 "batchItems": [
3 {
4 "query": "/chargingAvailability.json?chargingAvailability=00112233-4455-6677-8899-aabbccddeeff"
5 },
6 {
7 "query": "/chargingAvailability.json?chargingAvailability=00112233-4455-6677-8899-001122334455"
8 }
9 ]
10}

The preceding POST body contains example charging availability ID values. Proper charging availability ID values can be retrieved from a Search request.

Response data

Batch Submission response

On a successful Batch request submission, the Batch Search service responds with an HTTP 202 or an HTTP 303. The response has a Location header with a link to the Batch Download endpoint and no body. In case of an error, a body is present.

HTTP status codes

Code

Meaning & possible causes

202

Accepted: An HTTP response with a Location header that points where the batch results can be obtained. This code is used when redirectMode is set to manual.

303

See Other: An HTTP response with a Location header that points where the batch results can be obtained. This code is used when redirectMode is set to auto.

400

Bad Request:

  • Missing required parameters.
  • Exceeded maximum number of batch items.
  • Parameters did not pass validation.
403

Forbidden: The API Key is missing, inactive, invalid, not entitled to use Batch Search API over QPS (Queries per second) or over QPD (Queries per day). It can also occur when using HTTP instead of HTTPS.

404

Not Found: The requested resource could not be found, but it may be available again in the future.

405

Method Not Allowed: The client used an HTTP method other than POST.

414

Requested URI is too long: Indicates that the URI requested by the client is longer than the server is willing to interpret.

429

Too Many Requests: The API Key is over QPS (Queries per second).

500

An error occurred while processing the request. Please try again later.

502

Internal network connectivity issue. Please try again later.

503

Service currently unavailable. Please try again later.

504

Internal network connectivity issue or a request that has taken too long to complete.

Please try again later.

596

Service not found. Request contains an incorrect FQDN and/or path.

Response headers

Header

Description

Access-Control-Expose-Headers

A comma separated list of HTTP header names that browsers are allowed to access.


Value: Content-Length

Access-Control-Allow-Origin

A header instructing browsers to allow customer websites to contact the Batch Search service.


Value: *

Content-Encoding

The Batch Search service applies gzip compression to the responses if it is requested by the client with the Accept-Encoding header.


Value: gzip

Content-Type

The format of the response as chosen by the client (see the contentType request parameter).


Values: application/xml;charset=utf-8 and application/json;charset=utf-8.

Location

Indicates the location where the batch results can be downloaded.


Value: URI

Tracking-ID

An identifier for the request. If the Tracking-ID header was specified, it is replicated in the response. Otherwise, it is generated automatically by the service. It is only meant to be used for support and does not involve tracking of you or your users in any form.


Value: An identifier for the request.

Error response

The error response content type depends on the outputFormat parameter.

1<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
2 <batchResponse xmlns="http://api.tomtom.com/batch" formatVersion="0.0.1">
3 <error description="Validation of batch item 1 failed. Batch response format (XML) does not match content type of batch item query."/>
4 <detailedError>
5 <code>BadRequest</code>
6 <message>Bad Request</message>
7 <details>
8 <detail>
9 <code>MalformedBody</code>
10 <message>Validation of batch item 1 failed. Batch response format (XML) does not match content type of batch item query.</message>
11 <target>postBody</target>
12 </detail>
13 </details>
14 </detailedError>
15 </batchResponse>
1{
2 "formatVersion": "0.0.1",
3 "error": {
4 "description": "Validation of batch item 1 failed. Batch response format (JSON) does not match content type of batch item query."
5 },
6 "detailedError": {
7 "code": "BadRequest",
8 "message": "Bad Request",
9 "details": {
10 "code": "MalformedBody",
11 "message": "Validation of batch item 1 failed. Batch response format (JSON) does not match content type of batch item query",
12 "target": "postBody"
13 }
14 }
15}

Error response fields

Primary fields

Field

Description
formatVersion
string
Version of the batch error response format.
error
object

Simplified information about the error.


error

object


detailedError
object

Detailed information about the error.


detailedError

object

error object

Field Description
description
string

A human-readable description of the error. It is intended as an aid to developers and is not suitable for exposure to end users.

detailedError object

Field Description
code
string

One of the defined error codes.

message
string

A human-readable description of the error code. It is intended as an aid to developers and is not suitable for exposure to end users.

target
string

Optional. Target of the particular error.


Values:
  • The name of the request parameter.
  • postBody
details
array

Optional. An array of root causes (more detailed errors) that led to this error.


detailedError

object

innerError
object

Optional. A higher level of details about this error.


innerError

object

innerError object

Field Description
code
string

One of the defined error codes.

message
string

Optional. A human-readable representation of the error code. It is intended as an aid to developers and is not suitable for exposure to end users.

innerError
object

Optional.


A higher level of details about this error.


innerError

object

Error code hierarchy

List of predefined, hierarchical, human-readable error codes. Top level codes relate to HTTP error codes. They may be refined by error codes in details or innerError. Further levels of refinement are possible by nesting innerError inside innerError. In the future, the list may be extended with additional codes. The application must be ready for the occurrence of an unknown error code (e.g., by stopping error processing at the last understood level of detail).

Error code

Description

BadArgument

One of the request parameters was missing or did not pass validation. The target field contains the name of the related parameter.


Possible inner errors:

  • MissingRequiredParameter
  • InvalidParameterValue
  • IllegalParameter
  • ValueOutOfRange
BadRequest

Top level code for requests which resulted in a HTTP 400 Bad Request.
Possible root causes: BadArgument and MalformedBody

IllegalParameterUnsupported request parameter was specified.
InvalidParameterValueThe value of one of the parameters is invalid.
InternalServerError

Top level code for Requests which resulted in a HTTP 500 Internal Server Error. The service cannot handle the request right now, an unexpected condition was encountered.

MalformedBodyPOST body has unexpected format.
MissingRequiredParameterOne of the required parameters was not provided.
NotFound

Top level code for requests which resulted in a HTTP 404 Not Found caused by providing incorrect Request path.

ServiceUnavailable

Top level code for Requests which resulted in a HTTP 503 Service Unavailable. The service cannot handle the request right now, this is certainly a temporary state.

ValueOutOfRange

The value of one of the numeric parameters is out of the allowed range.