OpenSearch interface error handling update on CREODIAS

OpenSearch API error handling was updated on the 24th of October 2023.

A new parameter, RequestId, was introduced to help identify requests with errors. It appears in response only in case of an error. While contacting the support team regarding issues with the Catalog API, make sure to include RequestId.

Changes in error handling

a. Incorrect collection name

PREVIOUS response:

{
    "detail": {
        "ErrorMessage": "loadFromStore - Not Found",
        "ErrorCode": 404
        }
}

NEW response:

{
    "detail": {
        "ErrorMessage": "Unknown collection.",
        "ErrorCode": 404,
        "ErrorDetail": [
            {
                "loc": ["collection"],
                "msg": "Collection '<collection name presented in query>' does not exist.",
            },
        ],
        "RequestId": <request_id>,
    }
}

EXAMPLE:

Request:

https://datahub.creodias.eu/resto/api/collections/Sentinl2/search.json

New response example:

{
    "detail": {
        "ErrorMessage": "Unknown collection.",
        "ErrorCode": 404,
        "ErrorDetail": [
            {
                "loc": [
                    "collection"
                ],
                "msg": "Collection 'Sentinl2' does not exist."
                },
        ],
        "RequestID": "70970f42-e374-4e26-8778-41a1463e700d"
    }
}

b. Incorrect name of the query parameter (when the collection is not specified)

PREVIOUS response:

Currently no error is returned. The incorrect query parameter is ignored and not reflected in applied filters.

NEW response:

{
    "detail": {
        "ErrorMessage": "Unknown query parameter(s).",
        "ErrorCode": 400,
        "ErrorDetail": [
            {
                "loc": [<list of nonexisting parameters>],
                "msg": "Query parameters do not exist.",
            },
        ],
        "RequestId": <request_id>,
    }
}

EXAMPLE:

Request:

https://datahub.creodias.eu/resto/api/collections/search.json?productsType=S2MSI1C

Catalog API response:

{
    "detail": {
        "ErrorMessage": "Unknown query parameter(s).",
        "ErrorCode": 400,
        "ErrorDetail": {
            "loc": [
                "productsType"
            ],
            "msg": "Query parameters do not exist."
        },
        "RequestID": "d9f22173-4d56-44fd-ab18-35d6018c49d7"
    }
}

c. Incorrect name of the query parameter (when the collection is specified)

PREVIOUS response:

Currently no error is returned. The incorrect query parameter is ignored and not reflected in applied filters

NEW response:

{
    "detail": {
        "ErrorMessage": "Unknown query parameter(s).",
        "ErrorCode": 400,
        "ErrorDetail": [
            {
                "loc": [<list of nonexisting parameters>],
                "msg": "Query parameters do not exist or are not available for specified collection.",
            },
        ],
        "RequestId": <request_id>,
    }
}

EXAMPLE:

Query:

https://datahub.creodias.eu/resto/api/collections/Sentinel2/search.json?productType=S2MSI1C&startDat=2023-06-11&completionDte=2023-06-22

New response example:

{
    "detail": {
        "ErrorMessage": "Unknown query parameter(s).",
        "ErrorCode": 400,
        "ErrorDetail": {
            "loc": [
                "startDat",
                "completionDte",
            ],
            "msg": "Query parameters do not exist or are not available for specified collection.",
        },
        "RequestID": "25d522af-ba4e-4152-a368-9635d560e649"
    }
}

dataset parameter is not supported anymore and any query using it will result in error.

d. Incorrect value of the query parameter

An incorrect value of one or more of the following parameters is has been used in the query:

maxRecords	index	page	sortParam
sortOrder	exactCount	geometry	box
lon	lat	radius	startDate
completionDate	updated	published	published
publishedAfter	publishedBefore	status

PREVIOUS response:

{
    "detail": {
        "ErrorMessage": <error message>,
        "ErrorCode": 400
    }
}

NEW response:

{
    "detail": {
        "ErrorMessage": "Validation error.",
        "ErrorCode": 400,
        "ErrorDetail": [
            {
                "loc": [<list of parameters that error "msg" field relate to>],
                "msg”: <error message>}>,
            },
        ]
        "RequestId": <request_id>,
    }
}

EXAMPLE:

Query:

https://datahub.creodias.eu/resto/api/collections/search.json?startDate=2021-07-01T00:00:00Z&completionDate=2021-07-31T23:59:59Z&maxRecords=2001

New response example:

{
    "detail": {
        "ErrorMessage": "Validation error.",
        "ErrorCode": 400,
        "ErrorDetail": [
            {
                "loc": [
                    "maxRecords"
                ],
                "msg": "Input should be less than or equal to 2000."
            }
        ],
        "RequestID": "b3b4c0bb-9697-4ff8-b90c-4eb1b97a9914"
    }
}

For status parameter the only acceptable values will be:

• ONLINE

• OFFLINE

• ALL

Any other value results in an error.

e. Incorrect value type of the query parameter

PREVIOUS response:

{
    "detail": {
        "ErrorMessage": <error message>,
        "ErrorCode": 400
        }
}

NEW response:

{
    "detail": {
        "ErrorMessage": "Validation error.",
        "ErrorCode": 400,
        "ErrorDetail": [
            {
                "loc": [<list of parameters that error "msg" field relate to>],
                "msg”: <error message>}>,
            },
        ]
        "RequestId": <request_id>,
    }
}

EXAMPLE:

https://datahub.creodias.eu/resto/api/collections/search.json?orbitNumber=ascending

New response example:

{
    "detail": {
        "ErrorMessage": "Validation error.",
        "ErrorCode": 400,
        "ErrorDetail": [
            {
                "loc": [
                    "orbitNumber"
                ],
                "msg": "Proper value types for specified attribute query parameters are: 'orbitNumber'-integer"
            }
        ],
        "RequestID": "33e3ebb0-7d44-4dcd-8cb2-f60216c11cef"
    }
}

Additional changes

a. Update of the last link

The last link will be provided only when exactCount is used in the request.

Link last example:

{
    "rel": "last",
    "type": "application/json",
    "title": "last",
    "href":
"https://catalogue.dataspace.copernicus.eu/resto/api/collections/Sentinel2/search.json?page=19168&processingLevel=S2MSI1C&startDate=2023-07-01&completionDate=2023-07-31&sortParam=startDate&exactCount=1"
}

b. Update of the exactCount parameter

The exactCount parameter is not set by default to 1 (True) anymore. Now, users need to declare its value as 1 to receive totalResults count.