Troubleshooting Push source issues

This is for:

Developer System Administrator

When using a Push source to index content, issues may arise during HTTP requests to the Push API or later in the indexing pipeline. 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

Common Push API errors

400 - INVALID_JSON

Symptoms

Your API request fails with a 400 INVALID_JSON error.

Cause

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

Solution

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

  • If you’re pushing items, verify 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, verify 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), verify 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), verify that the request body minimally includes the compressedBinaryDataFileId key-value pair. For more information, see Use the compressedBinaryDataFileId property.

400 - ORGANIZATION_IS_PAUSED

Symptoms

Your API request fails with a 400 ORGANIZATION_IS_PAUSED error.

Cause

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

Solution

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

Symptoms

Your API request fails with a 401 UNAUTHORIZED error.

Cause

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

Solution

Include the Authorization: Bearer <MyAccessToken> header in your request. Replace <MyAccessToken> with your Push source API key.

If you 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

Symptoms

Your API request fails with a 401 INVALID_TOKEN error.

Cause

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

Solution

  • 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

Symptoms

Your API request fails with a 403 ACCESS_DENIED error.

Cause

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

Solution

  • 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)

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.

Cause

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

Solution

404 - ERROR_DESERIALIZING_BATCH_DOCUMENT_FROM_S3

Symptoms

Your API request fails with a 404 ERROR_DESERIALIZING_BATCH_DOCUMENT_FROM_S3 error.

Cause

A large file in a batch of items that you were trying to retrieve from your S3 bucket couldn’t be deserialized.

Solution

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

  • Verify that your JSON payload 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.

  • Verify that there are no duplicate keys within the JSON payload.

412 - DOCUMENT_LIMIT_EXCEEDED

Symptoms

Your API request fails with a 412 DOCUMENT_LIMIT_EXCEEDED error.

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

Cause

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

Solution

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

412 - INVALID_PARAMETER

Symptoms

Your API request fails with a 412 INVALID_PARAMETER error.

Cause

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

Solution

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

412 - INVALID_SECURITY_PROVIDER_TYPE

Symptoms

Your API request to disable or add/update a security identity fails with a 412 INVALID_SECURITY_PROVIDER_TYPE error and a message indicating that the security provider isn’t an expanded security provider.

Cause

You’re trying to use the Push API to manage identities in a security identity provider that wasn’t created for a Push source.

Solution

412 - MISSING_PARAMETER

Symptoms

Your API request fails with a 412 MISSING_PARAMETER error.

Cause

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

Solution

Pass a valid argument for all required path and query parameters of the request.

412 - SOURCE_DOES_NOT_EXIST

Symptoms

Your API request fails with a 412 SOURCE_DOES_NOT_EXIST error.

Cause

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

Solution

  • Verify that you’ve correctly spelled the sourceId of the target source.

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

Creating the first source in a new Coveo organization usually takes around 10 minutes, since the organization needs to be provisioned first. Once provisioned, creating subsequent sources takes only a few seconds.

413 - Request Entity Too Large

Symptoms

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

Cause

You’re trying to perform a push request whose total size exceeds the permitted maximum. For more information, see Request size constraints.

Solution

  • If you’re pushing a single compressed or uncompressed item, 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, try pushing smaller batches.

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

415 - UNSUPPORTED_MEDIA_TYPE

Symptoms

Your API request fails with a 415 UNSUPPORTED_MEDIA_TYPE error.

Cause

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

Solution

If you’re not uploading content to an AWS container, 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

Symptoms

Your API request fails with a 429 response. The error code depends on the specific quota you’ve reached, for example, TOO_MANY_REQUESTS, TOO_MANY_DOCUMENTS_DAILY, or RELATIONSHIP_UPDATE_RATE_LIMIT_EXCEEDED.

Also, the License & Usage (platform-ca | platform-eu | platform-au) page may show that you’ve reached a Push API quota.

Cause

  • You’ve exceeded one of your Push API quotas.

  • 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.

Solution

  • If you’ve exceeded one of your Push API quotas, wait until the quota resets. For example, wait until midnight UTC for a daily quota, and respect the quota going forward. Also, you can implement an exponential backoff strategy to retry your requests after a certain amount of time.

  • If you haven’t exceeded one of your Push API quotas, wait until your requests are no longer being throttled before using the service again. In the future, make Push API requests at a slower pace, especially after a period of inactivity.

For more information, see Push API quotas and constraints.

5XX

Symptoms

Your API request fails with a 5XX error.

Cause

The request encountered 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.

Solution

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

  • If you’re 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

Items don’t appear in search results after a successful push

Symptoms

Cause

A success response from the API means the request was received and queued, but it doesn’t mean the items were processed and are available in the index yet.

After a successful push, the items enter the indexing pipeline, where processing time may vary as it depends on factors such as indexing load and the number of items being processed.

As a result, there’s an expected delay between a successful API call and the items being searchable. This is normal behavior, not an error.

Solution

JSON deserialization error

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.

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.

Solution

When uploading batches of items to a file container, use JSON libraries or tools for your programming language to format the content correctly.

Total metadata size limit exceeded

Symptoms

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

Cause

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

Solution

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

Source refresh timeout

Symptoms

Cause

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

Solution

  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

Symptoms

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

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

Cause

The System.ServiceModel.Primitives package may be missing from your project.

Solution

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

Symptoms

Cause

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

Solution

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.

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

Symptoms

  • You performed a Delete old items request.

  • The status of the request was Success.

  • No items were deleted.

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.

Solution

Perform the Delete old items request again using an appropriate orderingId value. To find an appropriate value, inspect an item in your source to see its orderingId.

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

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.

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.

Solution

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