OpenSearch interface error handling update

Please be informed that the OpenSearch API error handling update is planned on the 24th October 2023.

Please also note that new responses with errors will provide the ‘RequestId’ which is intended to help identify the requests with errors. It is strongly recommended to include the ‘RequestId’ in your issues submitted to the support team in case of Catalog API problems.

The new error handling will cover the following issues:

1. Incorrect collection name:
   
   • Current response:
     
     {
"detail": {
"ErrorMessage": "loadFromStore - Not Found",
"ErrorCode": 404
}
}
   • New response:
     
     {
"detail": {
"ErrorMessage": "Unknown collection.",
"ErrorCode": 404,
"ErrorDetail": [
{
"loc": ["collection"],
"msg": "Collection '' does not exist.",
},
],
"RequestId": <request id>,
}
   • Request example:
     
     https://datahub.creodias.eu/resto/api/collections/Sentinl2/search.json
     Response:
     
     {
"detail": {
"ErrorMessage": "Unknown collection.",
"ErrorCode": 404,
"ErrorDetail": [
{
"loc": ["collection"],
"msg": "Collection 'Sentinl2' does not exist.",
},
],
"RequestId": "70970f42-e374-4e26-8778-41a1463e700d",
}
2. Incorrect name of the query parameter (when the collection is not specified):
   
   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 nonexistent parameters> ],
"msg": "Query parameters do not exist.",
},
],
"RequestId": <request id> ,
}
}
   • Request example:
     
     https://datahub.creodias.eu/resto/api/collections/search.json?productsType=S2MSI1C
     Response:
     
     {
"detail": {
"ErrorMessage": "Unknown query parameter(s).",
"ErrorCode": 400,
"ErrorDetail": [
{
"loc": ["productsType"],
"msg": "Query parameters do not exist.",
},
],
"RequestId": "d9f22173-4d56-44fd-ab18-35d6018c49d7" ,
}
}
3. Incorrect name of the query parameter (when the collection is specified):
   
   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": [],
"msg": "Query parameters do not exist or are now available for specified collection.",
},
],
"RequestId": <request id>,
}
}
     
   • Request example:
     
     https://datahub.creodias.eu/resto/api/collections/Sentinel2/search.json?productType=S2MSI1C&startDat=2023-06-11&completionDte=2023-06-22
     Response:
     
     {
"detail": {
"ErrorMessage": "Unknown query parameter(s).",
"ErrorCode": 400,
"ErrorDetail": [
{
"loc": [],
"msg": "Query parameters do not exist or are now available for specified collection.",
},
],
"RequestId": "25d522af-ba4e-4152-a368-9635d560e649",
}
}
     
   • Please note that dataset parameter will not be supported anymore. Any query with the dataset parameter will result in an error.
     
4. Incorrect value of the query parameter (maxRecords, index, page, sortParam, sortOrder, exactCount, geometry, box, lon, lat, radius, startDate, completionDate, updated, published, publishedAfter, publishedBefore, status)
   
   • Current response:
     
     {
"detail": {
"ErrorMessage": <error message> ,
"ErrorCode": 400
}
}
     
   • New response:
     
     {
"detail": {
"ErrorMessage": "Validation error.",
"ErrorCode": 400,
"ErrorDetail": [
{
"loc": [ <list of parameters error message relates to> ],
"msg”: <error message>,
},
]
"RequestId": <request id> ,
}
}
     
   • Request example:
     https://datahub.creodias.eu/resto/api/collections/search.json?startDate=2021-07-01T00:00:00Z&completionDate=2021-07-31T23:59:59Z&maxRecords=2001
     Response:
     
     {
"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" ,
}
}
     
   • Please note that for status parameter the only acceptable values will be:
     • ONLINE
     • OFFLINE
     • ALL
       
       Any other value will result in an error.
5. Incorrect value type of the query parameter
   
   • Current response:
     
     {
"detail": {
"ErrorMessage": <error message>,
"ErrorCode": 400
}
}
   • New response:
     
     {
"detail": {
"ErrorMessage": "Validation error.",
"ErrorCode": 400,
"ErrorDetail": [
{
"loc": [<list of parameters that error message relates to>],
"msg”: <error message>,
},
]
"RequestId": <request id>,
}
}
     
   • Request example:
     https://datahub.creodias.eu/resto/api/collections/search.json?orbitNumber=ascending
     Response:
     
     {
"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",
}
}

Please also note about the following change:

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

We recommend reviewing the upcoming changes to Catalogue OpenSearch API described above to avoid disruption to your current scripts or apps.