Troubleshooting

Common Issues and Resolution Steps

HTTP Errors

Design your application to log the returned response payload as it provides additional context into the nature of the error. The context helps in quickly determining the root cause and potential resolution.

400 - Bad Request

This type of error is most commonly due to an incorrect value provided in the query payload, such as providing a property that is unsupported, or a parameter value that does not exist or has been typed incorrectly.

Incorrect Field Value

The Records API provides multiple filters that you can use in queries by passing the value in the field property. These values are validated by the application, ensuring that it is within the currently available filters. Please refer to the Filters & Parameters for the complete list of filters.

Example of an error due to an incorrect field value.
{
    "error": {
        "id": "098537a6-9fb1-4fe4-aad4-6aa9bb61cdba",
        "code": "400",
        "message": "Validation error",
        "status": "Bad Request",
        "errors": [
            {
                "key": "requestBody",
                "reason": "Error at \"/criteria/field\": value is not one of the allowed values [\"recordType\",\"categoryPath\",\"locationType\",\"locationRole\",\"locationCode\",\"keyword\",\"keywordType\",\"uid\",\"recordStatus\",\"lastPublishedDate\",\"initialPublishedDate\",\"recordSubType\",\"updateCategory\",\"keywordStatus\",\"keywordIssuingAuthority\",\"countryKeywordIssuingAuthority\",\"subjectStatus\"]"
            }
        ]
    }
}

Incorrect Lookup Value

The Records API also validate the values provided in the query's value property, checking if all entries are valid concepts.

Example of an error due to an incorrect or non-existent concept.
{
    "error": {
        "code": "400",
        "id": "cd9367cf-8931-451e-8402-534d50b661f3",
        "message": "Validation error",
        "status": "Bad Request",
        "errors": [
            {
                "key": "requestBody",
                "reason": "The keyword value wcSourceKwd:ABCDE is not a valid keyword"
            }
        ]
    }
}

Incorrect or Incompatible Operator

The query operators are also validated, ensuring that what you provide within a query request is compatible with the field. Please refer to the Filters & Parameters for the list of fields and the allowed operators for each.

An example of an error due to an incorrect operator.
{
    "error": {
        "code": "400",
        "id": "0c8d264a-93b3-4081-af24-f815ea64d2a5",
        "message": "Validation error",
        "status": "Bad Request",
        "errors": [
            {
                "key": "requestBody",
                "reason": "request.body.operator includes is not supported for the request.body.field lastPublishedDate."
            }
        ]
    }
}

Invalid Date Format

The formats of datetime inputs are also validated.

Refer to the Records API and References API for the accepted input date formats.

{
    "error": {
        "code": "400",
        "id": "4664ee5e-4e68-424c-ad07-f6e975ef9a69",
        "message": "Validation error",
        "status": "Bad Request",
        "errors": [
            {
                "key": "requestBody",
                "reason": "Invalid datetime format. request.body.criteria.value or request.body.query.criteria.x.value should be in the ISO-8601 format"
            }
        ]
    }
}

401 - Unauthorized

An unauthorized error is almost always due to two possible reasons:

Incorrect credentials being provided.
Expired bearer token.

A typical HTTP/401 message due to invalid credentials when retrieving a token.
{
    "error_description": "Invalid client or client credentials.",
    "error": "invalid_client"
}

Possible reasons:

Incorrect or incomplete credential information entered into your application's configuration. Please re-check your source.
Credentials from a different account. Please verify that the credentials are from the expected account.
Deactivated or deleted account, particularly if this set of credentials previously worked.

When the token has expired, an HTTP/401 error will be provided when it is used in an API request.

An HTTP/401 error when a token has expired.
{
    "error": {
        "id": "1d710cb2-6e18-4d25-b0de-9847b025e4ff",
        "code": "401",
        "message": "token expired",
        "status": "Unauthorized"
    }
}

Design your application to retrieve a new token just before token expiration (e.g., < 30 seconds) or when receiving this error message.

Please see the Authentication & Authorisation for more details.

403 - Forbidden

While credentials can be authenticated, it may not be authorised to access the resource or data. World-Check On Demand checks the entitlements or claims associated with the provided token and either prevent access to the resource or data being requested.

The bearer token must be the JSON Web Token (JWT) type and must contain the right entitlements. These entitlements must be requested through the scope parameter when getting a token.

Error message when the token does not contain the right entitlements for the requested data.
{
    "error": {
        "code": "403",
        "id": "d987654321-3f56-4556-967d-123abc987",
        "message": "Access denied",
        "status": "Forbidden",
        "errors": [
            {
                "key": "entitlement",
                "reason": "access denied. No entitlement found in the token."
            }
        ]
    }
}

Possible reasons:

Missing scope parameter in the token request.
Incorrect value provided for the scope parameter in the token request. Please refer to the scope values for details.
Incorrect token type. Check the value provided for the aud parameter. Please refer to the audience values for details.

Error message when the token does not contain the right entitlements for the requested resource.
{
    "error": {
        "id": "4c15d59e-41c7-4b66-a0ba-d07b454c3103",
        "code": "insufficient_scope",
        "message": "access denied. Scopes required to access the resource: [trapi.risk-intel.wcod.records.read]. Missing scopes: [trapi.risk-intel.wcod.records.read]",
        "status": "Forbidden"
    }
}

The list of possible reasons are the same as above.

404 - Not Found

In World-Check On Demand, this error will only be returned due to an incorrect resource path in the URL. Please refer to the API Reference for the correct resource paths.

405 - Method Not Allowed

World-Check On Demand endpoints only accept a limited set of methods:

Records API: POST and OPTIONS
References API: GET and OPTIONS

Please refer to the API Reference for the allowed methods for each resource.

Example of a request using an unsupported method against the /records resource.
curl --location --head 'https://api.refinitiv.com/risk-intel/v1/records?limit=200' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{}'

API Response when an unsupported method is used.
HTTP/1.1 405 Method Not Allowed
Date: Fri, 05 Sep 2025 23:41:40 GMT
Connection: close
X-Amzn-Trace-Id: Root=1-68bb7534-595ffa4313af5c0551d96628
X-Served-By: region=ap-southeast-1; cid=eaf055d5fe634f7c8b87944fde3bf941

429 - Too Many Requests

To manage system performance and service protection, World-Check On Demand enforces rate limits on its resources. When the first level thresholds of these limits are breached, an HTTP/429 will be sent as a response.

An example of an API response indicating that there had been too many requests against an endpoint.
{
  "error": {
    "code": "429",
    "id": "90656dfa-d824-44f9-87d3-d503284cd18c",
    "message": "too many requests for /risk-intel/v1/records [POST]",
    "status": "Too Many Requests"
  }
}

When this message is received, the calling application should perform an exponential backoff. Please refer to the API Rate Limits for more details.

500 - Internal Server Error

When certain errors are unexpected or unhandled, the API may return this error.

An unexpected error may return with the Internal Server Error message.
{
  "error": {
    "code": "500",
    "id": "ff8b47a7-d547-4332-bd5b-346e7286cf67",
    "message": "Internal Server Error",
    "status": "Internal Server Error",
    "errors": [
      {
        "key": "Internal server error",
        "reason": "An unknown error occurred. Please try again or contact World-Check On Demand Support."
      }
    ]
  }
}

When this message is received, the calling application should perform an exponential backoff as most of these are likely to resolve on its own in a few seconds or minutes. Please raise a case with LSEG if the error persists after several spaced attempts.

502 - Bad Gateway

On rare cases, this error may appear and is almost always due to an infrastructure issue on LSEG.

<html>

<head>
    <title>502 Bad Gateway</title>
</head>

<body>
    <center>
        <h1>502 Bad Gateway</h1>
    </center>
</body>

</html>

503 - Unavailable

On rare cases, this error may appear and is almost always due to an infrastructure issue on LSEG.

<html>

<body>
    <h1>503 Service Unavailable</h1>
    <p>The server is currently unable to handle the request.</p>
</body>

</html>

504 - Gateway Timeout

There may be certain situations where the API is slow to respond or returns this error after 60 seconds of no response. This may rarely happen with complex queries or query counts.

<html>

<head>
    <title>504 Gateway Time-out</title>
</head>

<body>
    <center>
        <h1>504 Gateway Time-out</h1>
    </center>
</body>

</html>

Other Errors or API Behavior

Slow Response

There may be certain situations where the API appears slow to respond without returning an HTTP/504 (Gateway Timeout) error.

Possible reasons:

Unusually complex query request. Please review if the issued query parameters in the request are necessary. It will ease the processing time if the query is simplified and additional filtering is done locally.
A combination of very large records and a large limit value resulting in a very large API response page. This may happen during delta retrievals when there are significant sanctions record updates, particularly on older records with many updates and details over the years. When the slow responses are only happening during delta runs, it is recommended to lower the page limit value to 100 or less, which lowers the risk of time outs.

BEST PRACTICE

With World-Check On Demand, it is highly recommended to design your application and ingestion to do a delta run for new, updated, and deleted records and references on the highest frequency as possible, such as every 1 minute. This provides two benefits: (a) data freshness at par with LSEG, and (b) fast delta performance as only a small number of records are new/updated/deleted in the past 1 minute.

Duplicate Records on Delta Requests

There may be certain scenarios where delta requests end up returning record versions that are already present in the local database.

Possible reasons:

The use of the gte operator. Delta retrievals are primarily driven by the provided starting point timestamp, normally using the lastPublishedDate filter with the gt operator. If the gte operator is used instead then there is a small chance that a record returned in the previous delta run gets returned in the next one. This is because the records returned are up to the requestDate, which is usually used as the subsequent lastPublishedDate value.
Overlapping delta window. When delta windows are accidentally or purposely overlapped (e.g., hourly delta with a 2-hour lookback) duplicate record versions are expected.
Using the same requestDate value across different requests within a delta run. The requestDate for a specific API request should be stored and used only for that specific request during delta runs (as lastPublishedDate value). Using the same requestDate value across different API requests will potentially cause duplicate records to be returned.

Please refer to the recommended delta retrieval approach in the Updates / Deltas section of the Guides.

HTTP Errors​

400 - Bad Request​

Incorrect Field Value​

Incorrect Lookup Value​

Incorrect or Incompatible Operator​

Invalid Date Format​

401 - Unauthorized​

403 - Forbidden​

404 - Not Found​

405 - Method Not Allowed​

429 - Too Many Requests​

500 - Internal Server Error​

502 - Bad Gateway​

503 - Unavailable​

504 - Gateway Timeout​

Other Errors or API Behavior​

Slow Response​

Duplicate Records on Delta Requests​

HTTP Errors

400 - Bad Request

Incorrect Field Value

Incorrect Lookup Value

Incorrect or Incompatible Operator

Invalid Date Format

401 - Unauthorized

403 - Forbidden

404 - Not Found

405 - Method Not Allowed

429 - Too Many Requests

500 - Internal Server Error

502 - Bad Gateway

503 - Unavailable

504 - Gateway Timeout

Other Errors or API Behavior

Slow Response

Duplicate Records on Delta Requests