HTTP response errorsSpringboard API

Table of Contents

Client error codes 4xx
Server error codes 5xx
Retry logic for 5xx and client-side timeout errors
- Retry process details

The Springboard APIs use standard HTTP response status codes. For example, success codes are in the 2xx range, client error codes are in the 4xx range, and so on.

Error responses include the title, message, and status code.

Some HTTP status codes are specific to one or more endpoints, but not all. Review the API configuration specifications for complete details on which HTTP responses apply to your endpoint.

Client error codes `4xx`

400 - Invalid value 'FIELD_VALUE' in field 'query'. Query is too short. Must be at least 3 characters in length.

The query field requires a value of 3 or more characters. If there are less than 3 characters, this error is generated.

Example:

Request

curl --request POST \
  --url https://e2edc6de-ea00-404e-a58e-9c3810fb0c91.applications.lucidworks.com/query/searchahead \
  --header 'Authorization: Bearer {placeholderAccessToken}' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "st",
    "utcOffset": "-07:00",
    "sessionId": "864782f0-af36-4dee-8430-9e73d6006eaa"
  }'

Response

Invalid value in field query. Query is too short. Must be at least 3 characters in length.

Solution

Enter a value of 3 or more characters in the query field. In this example, the invalid value st in the query field is less than 3 characters. Correct the value in the query field.

400 - Request body contains field 'FIELD_NAME' which cannot be repeated

The request body includes a field that cannot be repeated.

Example:

Request

curl --request POST \
  --url https://e2edc6de-ea00-404e-a58e-9c3810fb0c91.applications.lucidworks.com/query/search \
  --header 'Authorization: Bearer {placeholderAccessToken}' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "book",
    "utcOffset": "-04:00",
    "utcOffset": "-04:00",
    "sessionId": "864782f0-af36-4dee-8430-9e73d6006eaa"
  }'

Response

Request body contains field utcOffset that cannot be repeated.

Solution

Remove the repeated field. In this example, remove the duplicate instance of utcOffset.

400 - Request contains more than one signal

The request body includes multiple signal objects, but the API only accepts one signal at a time.

Example:

Request

curl --request POST \
  --url https://e2edc6de-ea00-404e-a58e-9c3810fb0c91.applications.lucidworks.com/signals \
  --header 'Authorization: Bearer {placeholderAccessToken}' \
  --header 'Content-Type: application/json' \
  --data '[{
    "signalType": "click",
    "documentId": "441eb3be-7de6-470a-8141-e416a15c7db1-6a092bd4-5098-466c-94aa-40bf68294303-68708807657148371333355819934570439731",
    "sessionId": "864782f0-af36-4dee-8430-9e73d6006eaa",
    "utcOffset": "+04:00",
    "timestamp": 1655483226523
  },
  {
    "signalType": "click",
    "documentId": "441eb3be-7de6-470a-8141-e416a15c7db1-6a092bd4-5098-466c-94aa-40bf68294303-68708807657148371333355819934570439731",
    "sessionId": "864782f0-af36-4dee-8430-9e73d6006eaa",
    "utcOffset": "+04:00",
    "timestamp": 1655483226987
  }]'

Response

Request contains more than one signal.

Solution

Submit each signal separately by sending individual POST requests.

400 - Request body contains field 'FIELD_NAME' with invalid value 'FIELD_VALUE'

Verify that your request body adheres to the formatting requirements found in the API specifications. If your request body uses a string for a field value that must be a number, this error may result. For example, alphabetical characters are included in the utcOffset field, which is a time zone formatted as +hh:mm.

Example:

Request

curl --request POST \
  --url https://e2edc6de-ea00-404e-a58e-9c3810fb0c91.applications.lucidworks.com/query/searchahead \
  --header 'Authorization: Bearer {placeholderAccessToken}' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "book",
    "utcOffset": "abc-07:00",
    "sessionId": "864782f0-af36-4dee-8430-9e73d6006eaa"
  }'

Response

Request body contains field utcOffset with invalid value abc-07:00.

Solution

Correct the format of the value in the field.

400 - Request body contains field 'FIELD_NAME' with invalid value 'FIELD_VALUE' for application type 'APPLICATION_TYPE'

Verify that your request body adheres to the formatting requirements found in the API specifications for your application.

Example:

Request

curl --request POST \
  --url https://e2edc6de-ea00-404e-a58e-9c3810fb0c91.applications.lucidworks.com/signals \
  --header 'Authorization: Bearer {placeholderAccessToken}' \
  --header 'Content-Type: application/json' \
  --data '{
    "signalType": "visit",
    "documentId": "441eb3be-7de6-470a-8141-e416a15c7db1-6a092bd4-5098-466c-94aa-40bf68294303-68708807657148371333355819934570439731",
    "sessionId": "864782f0-af36-4dee-8430-9e73d6006eaa",
    "utcOffset": "+04:00",
    "timestamp": 1655483226523
  }'

Response

Request body contains the field signalType with invalid value visit.

Solution

Use a valid value in the field signalType, such as click.

400 - Request body contains field 'FIELD_NAME' with value 'FIELD_VALUE' that cannot be repeated

The request body is using the same field and value more than once. Remove the repeated value from your request body.

Example:

Request

curl --request POST \
  --url https://e2edc6de-ea00-404e-a58e-9c3810fb0c91.applications.lucidworks.com/query/searchahead \
  --header 'Authorization: Bearer {placeholderAccessToken}' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "book",
    "utcOffset": "-04:00",
    "sessionId": "864782f0-af36-4dee-8430-9e73d6006eaa",
    "filters": [
      {"field": "document.languageCode", "values": ["en"]},
      {"field": "document.languageCode", "values": ["fr"]}
    ]
  }'

Response

Request body contains field filter.field with value document.languageCode that cannot be repeated.

Solution

Remove the repeated field. In this example, remove the duplicate instance of document.languageCode. You can specify multiple language codes by using an array:

{"field": "document.languageCode", "values": ["en", "fr"]}

400 - Request body contains invalid field 'FIELD_NAME'

The request body includes a field that is not recognized by the API. Verify that your request body does not have a typo in one of the field names and adheres to the list of fields supported by the API specifications.

Example:

Request

curl --request POST \
  --url https://e2edc6de-ea00-404e-a58e-9c3810fb0c91.applications.lucidworks.com/query/detail \
  --header 'Authorization: Bearer {placeholderAccessToken}' \
  --header 'Content-Type: application/json' \
  --data '{
    "is": "441eb3be-7de6-470a-8141-e416a15c7db1-6a092bd4-5098-466c-94aa-40bf68294303-68708807657148371333355819934570439731",
    "utcOffset": "-07:00",
    "sessionId": "864782f0-af36-4dee-8430-9e73d6006eaa"
  }'

Response

Request body contains invalid field is.

Solution

Correct the name of the field. In this example, change is to id.

400 - Request body contains invalid JSON

This error indicates the format for the JSON payload or content types are not correct.

API request processing priority. When an API request is sent, the JSON is validated before the content of the message. The invalid JSON error can indicate incorrect JSON formatting as well as invalid content format. For example, if an integer format is designated, but its value contains text, an invalid JSON error is generated.

Example:

Request

curl --request POST \
  --url https://e2edc6de-ea00-404e-a58e-9c3810fb0c91.applications.lucidworks.com/query/search \
  --header 'Authorization: Bearer {placeholderAccessToken}' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": book,
    "utcOffset": "-07:00",
    "sessionId": "864782f0-af36-4dee-8430-9e73d6006eaa"
  }'

Response

Request body contains invalid JSON.

Solution

Review the request to ensure the JSON formatting requirements are followed and the values for the content types are accurate. To check the JSON, it may help to use a JSON validator to find and resolve the issue. In this example, the double quotes (") are missing from the query value, book.

400 - Request body is missing required field 'FIELD_NAME'

The request body is missing at least one required field. Verify that your request body includes all of the required fields, as indicated by the API specifications.

Example:

Request

curl --request POST \
  --url https://e2edc6de-ea00-404e-a58e-9c3810fb0c91.applications.lucidworks.com/query/searchahead \
  --header 'Authorization: Bearer {placeholderAccessToken}' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "example",
    "sessionId": "864782f0-af36-4dee-8430-9e73d6006eaa"
  }'

Response

Request body is missing required field utcOffset.

Solution

Add all required fields to the request body. In this example, the utcOffset field is missing from the request body.

404 - Document 'DOCUMENT_ID' was not found

The value submitted in the id field of the request was not found in the URL being searched.

Example:

Request

curl --request POST \
  --url https://e2edc6de-ea00-404e-a58e-9c3810fb0c91.applications.lucidworks.com/query/detail \
  --header 'Authorization: Bearer {placeholderAccessToken}' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "1234578911234556799876",
    "utcOffset": "-07:00",
    "fieldList": [
      "document.title"
    ],
    "sessionId": "864782f0-af36-4dee-8430-9e73d6006eaa"
  }'

Response

Document id was not found.

Solution

Correct the value in the id field.

Server error codes `5xx`

The 5xx server error codes indicate an issue with the server used in your request. These errors can occur with any request, and activate the retry logic process.

Error	Response
500	Internal Server Error
503	Service Unavailable
504	Gateway Timeout

Error

Response

500

Internal Server Error

503

Service Unavailable

504

Gateway Timeout

Retry logic for 5xx and client-side timeout errors

The following errors indicate a temporary or transient issue, and activate the retry logic process:

HTTP response code 500
HTTP response code 503
HTTP response code 504
Client-side request timeout
Client-side connection timeout

The retry process exponentially increments the delay with each retry. The maximum number of retries is 6.

Retry number	Delay until next retry attempt
1	1 second
2	2 seconds
3	4 seconds
4	8 seconds
5	16 seconds
6	32 seconds

Retry process details

If a retry attempt generates an error that does not activate another retry, the process ends. For example, if the first retry generates a 404 error, no more retries are attempted.

If a retry attempt generates a different error that activates the retry process, the process continues. For example, if the initial error returned is a 500 error and the first retry generates a client-side connection timeout, the second retry is activated.

If all retries have been attempted and the request is not successful, the response error from the last retry attempt must be analyzed to resolve the issue. For example, if the sixth retry generates a 503 error, begin troubleshooting to determine why the service is unavailable.

If the error resolution requires assistance from Lucidworks, click the Support link and add the steps that led to the error. Also include the API URL or page information and the request body. For more information, see Contact support.