Troubleshooting Push source issues

This is for:

Developer System Administrator

This article outlines the common issues encountered when indexing content using a Push source.

Issues may arise during HTTP requests to the Push API. The Coveo Push API provides error codes that can help diagnose these issues. This article lists common Push API errors, their likely causes, and suggested resolutions.

When using the Push API to manage items in a source, the service doesn’t immediately add, update, or delete content in the index. A Push API request typically triggers the indexing process, which is asynchronous. Even if an API request returns a success status code, a failure can still occur downstream in the Coveo indexing pipeline.

Indexing pipeline diagram
Diagram showing indexing process | Coveo

This article also addresses issues that aren’t specifically related to Push API requests, many of which the Log Browser (platform-ca | platform-eu | platform-au) can help diagnose.

Common Push API errors

400 - INVALID_JSON

Context and symptoms

Your API request fails with a 400 INVALID_JSON error.

Likely cause and resolution

Cause

The body of your Push API request may be incorrectly formatted, or it may lack certain required key-value pairs.

Resolution

  • Use a JSON validation tool to ensure that the body of your request is valid JSON.

  • If you’re pushing items, ensure that the request body is correctly formatted. For more information, see Item models.

    The request body must not contain any duplicate keys or sub-objects. For more information, see About Push Source Item Metadata.

  • If you’re pushing an uncompressed item, ensure that the request body minimally includes the data key-value pair. For more information, see Use the data property.

  • If you’re pushing a small compressed item (less than 5 megabytes), ensure that the request body minimally includes the compressedBinaryData key-value pair. For more information, see Use the compressedBinaryData property.

  • If you’re pushing a batch of items or a single large compressed item (5 megabytes or more), ensure that the request body minimally includes the compressedBinaryDataFileId key-value pair. For more information, see Use the compressedBinaryDataFileId property.

400 - ORGANIZATION_IS_PAUSED

Context and symptoms

Your API request fails with a 400 ORGANIZATION_IS_PAUSED error.

Likely cause and resolution

Cause

You’re attempting to make a request against a Coveo organization that’s currently inactive.

Resolution

Reactivate your organization by logging in to the Coveo Administration Console (platform-ca |platform-eu | platform-au). Then, try pushing your items again.

401 - UNAUTHORIZED

Context and symptoms

Your API request fails with a 401 UNAUTHORIZED error.

Likely cause and resolution

Cause

You’re trying to make an unauthenticated Push API request.

Resolution

Ensure that you include the Authorization: Bearer <MyAccessToken> header in your request. Replace <MyAccessToken> with your Push source API key.

If you currently don’t have an API key, select your source on the Sources (platform-ca | platform-eu | platform-au) page, and then click Create API key in the Action bar to create one.

401 - INVALID_TOKEN

Context and symptoms

Your API request fails with a 401 INVALID_TOKEN error.

Likely cause and resolution

Cause

The Coveo Platform doesn’t recognize the access token you’re using to authenticate your Push API request.

Resolution

  • If you’re using an API key to authenticate your call, this key may have been disabled or deleted in the target Coveo organization, or your IP address may not have access to this key. Ask an administrator to create a new API key with the required privileges for you. To do so, they can select your source on the Sources (platform-ca | platform-eu | platform-au) page, and then click Create API key in the Action bar.

  • If you’re using an OAuth2 token to authenticate your call, this token may be expired. Try again using a fresh Coveo OAuth 2.0 token.

403 - ACCESS_DENIED

Context and symptoms

Your API request fails with a 403 ACCESS_DENIED error.

Likely cause and resolution

Cause

The access token you’re using to authenticate your Push API request doesn’t grant you sufficient privileges to perform the request.

Resolution

  • If you’re using an API key to authenticate your call, this API key may not have the required privileges. Ask an administrator to create a new API key for you with the required privileges on the Push source. To do so, they can select your source on the Sources (platform-ca | platform-eu | platform-au) page, and then click Create API key in the Action bar.

  • If you’re using an OAuth 2.0 token to authenticate your call, your identity may not have the required privileges in the target Coveo organization. Ask an administrator to grant you these privileges or to create an API key for you with the required privileges on the Push source. To do so, they can select your source on the Sources (platform-ca | platform-eu | platform-au) page, and then click Create API key in the Action bar.

403 - ACCESS_DENIED (Request has expired)

Context and symptoms

  • You’re pushing a batch of items to a file container.

  • The API request fails with a 403 ACCESS_DENIED error and a message indicating that the request has expired.

Likely cause and resolution

Cause

The file container uploadUri you’re using to push items has expired. File container URLs are only valid for 60 minutes.

Resolution

404 - ERROR_DESERIALIZING_BATCH_DOCUMENT_FROM_S3

Context and symptoms

Your API request fails with a 404 ERROR_DESERIALIZING_BATCH_DOCUMENT_FROM_S3 error.

Likely cause and resolution

Cause

A large file in a batch document that you were trying to retrieve from your S3 Bucket was unable to be deserialized.

Resolution

  • If you’re pushing uncompressed raw textual item data, ensure that it’s UTF-8 encoded.

  • Ensure that your batch document is a valid JSON object.

  • Consider decreasing or splitting up the item update into smaller batches. For more information, see Manage batches of items in a Push source.

  • Ensure that there are no duplicate keys within the JSON batch document.

412 - DOCUMENT_LIMIT_EXCEEDED

Context and symptoms

Your API request fails with a 412 DOCUMENT_LIMIT_EXCEEDED error.

In addition, the System Performance (platform-ca | platform-eu | platform-au) page may show that you’ve exceeded the maximum number of items you can index.

Likely cause and resolution

Cause

You have reached the maximum number of items you can index with the Push API.

Resolution

Delete items in one of your Push sources, preferably using a batch call, or delete one of your Push sources.

412 - INVALID_PARAMETER

Context and symptoms

Your API request fails with a 412 INVALID_PARAMETER error.

Likely cause and resolution

Cause

At least one of the arguments you provided when making your Push API request is invalid.

Resolution

Ensure that all of the arguments you pass when making your request are of the expected type (that is, Boolean, integer, long, etc.).

412 - MISSING_PARAMETER

Context and symptoms

Your API request fails with a 412 MISSING_PARAMETER error.

Likely cause and resolution

Cause

You didn’t provide a value for at least one of the required parameters of your Push API request.

Resolution

Ensure that you pass a valid argument for all of the required path and query parameters of the request.

412 - SOURCE_DOES_NOT_EXIST

Context and symptoms

Your API request fails with a 412 SOURCE_DOES_NOT_EXIST error.

Likely cause and resolution

Cause

The Coveo Platform can’t find the sourceId you provided as an argument when making your Push API request.

Resolution

  • Ensure that you have correctly spelled the sourceId of the target source.

  • Ensure that the source you want to push content into has been successfully created in the target Coveo organization.

Creating the very first source in a new Coveo organization usually takes around 10 minutes, since this organization needs to be provisioned first.

Once the organization has been successfully provisioned, though, creating subsequent sources should only take a few seconds.

413 - Request Entity Too Large

Context and symptoms

Your API request fails with a 413 Request Entity Too Large error.

Likely cause and resolution

Cause

You’re trying to perform a push request whose total size exceeds the allowed limit. For more information, see Push API Limits - Request Size Limits.

Resolution

  • If you’re pushing a single compressed or uncompressed item whose data size exceeds 5 megabytes, use a large file container to push the item, rather than directly providing its data or compressedBinaryData in the body of the request. For more information, see Use the compressedBinaryDataFileId property.

  • If you’re pushing a batch of items whose total size exceeds 256 megabytes, try pushing smaller batches.

  • If you’re using a large file container to push a single large item whose uncompressed size exceeds 256 megabytes, try compressing the item using one of the supported algorithms (Deflate, GZip, LZMA, or ZLib) before pushing it again.

415 - UNSUPPORTED_MEDIA_TYPE

Context and symptoms

Your API request fails with a 415 UNSUPPORTED_MEDIA_TYPE error.

Likely cause and resolution

Cause

You’re trying to make a Push API request using the wrong content type.

Resolution

If you’re not uploading content to an AWS container, ensure that you include the Content-Type: application/json HTTP header in your request.

If you’re uploading content to an AWS container, include the Content-Type: application/octet-stream and x-amz-server-side-encryption: AES256 headers instead. For more information, see Use the compressedBinaryDataFileId property.

429

Context and symptoms

Your API request fails with a 429 response. The precise error code depends on the exact limit you’ve exceeded, for example, TOO_MANY_REQUESTS, TOO_MANY_DOCUMENTS_DAILY, or RELATIONSHIP_UPDATE_RATE_LIMIT_EXCEEDED.

In addition, the System Performance (platform-ca | platform-eu | platform-au) page may show that you’ve reached a Push API limit.

Likely cause and resolution

Cause

  • You have exceeded one of your Push API limits.

  • This error can also occur when first using the Push API after a period of inactivity (around 15 minutes). In such cases, the Push API needs to perform requests to other Coveo APIs, and it’s possible to exceed the allowed number of requests in a given amount of time, or the allowed number of concurrent requests to those other APIs. As a consequence, you may be throttled by those other APIs.

  • Coveo declined your request due to a reduced indexing capacity.

Resolution

  • If you have exceeded one of your Push API limits, wait until the limit resets. For example, wait until midnight UTC for a daily limit, and ensure you respect the limit going forward. In addition, you can implement an exponential backoff strategy to retry your requests after a certain amount of time.

  • If you have not exceeded one of your Push API limits, wait until your requests are no longer being throttled before using the service again. In the future, ensure that you make Push API requests at a slower pace, especially after a period of inactivity.

For more information, see Push API limits.

5XX

Context and symptoms

Your API request fails with a 5XX error.

Likely cause and resolution

Cause

You have triggered an unhandled error, or there’s an issue with the Push API service itself, or with AWS. For more information, see Error Handling Patterns in API Gateway and AWS Lambda.

Resolution

  • If you’re getting a 502 Bad Gateway error, ensure that the documentId for the item is properly URL-encoded, and then try again.

  • If you’re obviously not responsible for the error, try performing the request again (with an exponential backoff). AWS issues typically resolve themselves, given enough time.

  • You can monitor the status of Coveo from status.cloud.coveo.com.

Indexing process and other issues

JSON deserialization error

Context and symptoms

  • You pushed a batch of items to a Coveo source, but some or all of the items failed to be indexed.

  • In the Log Browser (platform-ca | platform-eu | platform-au), you see the ERROR_DESERIALIZING_BATCH_DOCUMENT_FROM_S3 error code during the Consuming stage.

Likely cause and resolution

Cause

The batch of items you uploaded to the file container contains improperly escaped or encoded characters. For example, the batch may contain double quotes in string values that should be escaped.

See the JSON standard documentation rules regarding strings.

Resolution

When uploading batches of items to a file container, use JSON libraries or tools for your programming language to ensure proper formatting.

Total metadata size limit exceeded

Context and symptoms

When trying to push an item to your Coveo source, the Log Browser (platform-ca | platform-eu | platform-au) shows the document as rejected with the TOTAL_METADATA_SIZE_EXCEEDS_LIMIT error code.

Likely cause and resolution

Cause

The total metadata size of the item you’re trying to push exceeds the limit of 52428800 bytes.

Resolution

The limit can’t be increased. You must reduce the size of the metadata you’re trying to push.

Source refresh timeout

Context and symptoms
Likely cause and resolution

Cause

The source was left in the REBUILD status for too long without any activity.

Resolution

  1. Perform a Set the status of a Push source request to set the source status to REBUILD.

  2. Once the source shows as Retrieving content, perform another Set the status of a Push source request to set the source status back to IDLE.

  3. After a few minutes, the source will return to the idle state and display Ready to receive content.

SSL connection issue with the C# Platform SDK

Context and symptoms

  • You’re using the Coveo C# Platform SDK to push a batch of items to a Coveo source.

  • You get a The SSL connection could not be established, see inner exception error.

Likely cause and resolution

Cause

The following package may be missing: System.ServiceModel.Primitives.

Resolution

Add the System.ServiceModel.Primitives NuGet package to your project. See Coveo.Connectors.Utilities.PlatformSdk for the .NET framework the current version of the SDK targets.

Out of sequence operation

Context and symptoms
Likely cause and resolution

Cause

You provided orderingId values on add, update, or delete requests that break the chronological sequence.

Resolution

Depending on the severity of the situation, you may need to reset the Push source.

To prevent this issue from happening again, don’t provide orderingId values on Push API requests when the Coveo service automatically assigns this value as the current 13-digit number of milliseconds since the Unix Epoch.

If you need to use the Delete old items request, you can inspect an item to find its orderingId value.

"Delete old items" request doesn’t delete items

Context and symptoms

  • You performed a Delete old items request.

  • The status of the request was Success.

  • No items were deleted.

Likely cause and resolution

Cause

The orderingId parameter represents the 13-digit number of milliseconds since the Unix Epoch. The orderingId value you set in the request is lower than that of all items in the source.

Resolution

Perform the Delete old items request again using an appropriate orderingId value. To get an idea of an appropriate orderingId value for the API request, you can inspect an item in your source to find its orderingId value.

Item is set as HTML in the payload but indexed as plain text

Context and symptoms

  • You added or updated an item, whether using the Add or update an item HTTP request or by pushing a batch of items.

  • You specified in your payload that the item is an HTML item. For example, your payload may have included the following key-value pairs:

    {
  "data": "<article>This is an HTML item.</article>",
  "fileExtension": ".html"
}

  • The Content Browser (platform-ca | platform-eu | platform-au) shows the item content indexed as raw text. For example, with a TXT file type or with a Quick view showing the raw item data, including the HTML tags.

Likely cause and resolution

Cause

The document processing manager (DPM) is unable to detect the file type based on the item content. The DPM doesn’t consider the <article> tag as a strong enough signal that the file type is HTML.

Resolution

Wrap the item content in stronger HTML tags, such as <html> and <body>, to help the DPM detect the file type as HTML. For example, your payload may have to look like the following:

{
  "data": "<html><body><article>This is an HTML item.</article></body></html>",
  "fileExtension": ".html"
}