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 calls 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 call typically triggers the indexing process, which is asynchronous. Therefore, an API call may be successfully executed and return a success status code, but the indexing process itself could still fail further downstream.

Indexing process 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

Note

Context and symptoms

Your API call fails with a 400 INVALID_JSON error.

Likely cause and resolution

Cause

The body of your Push API call 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 call is valid JSON.

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

    The request body must not contain any duplicate keys or sub-objects (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 (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 (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 (see Use the compressedBinaryDataFileId property).

400 - ORGANIZATION_IS_PAUSED

Note

Context and symptoms

Your API call 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

Note

Context and symptoms

Your API call fails with a 401 UNAUTHORIZED error.

Likely cause and resolution

Cause

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

Resolution

Ensure that you include the Authorization: Bearer <MyAccessToken> header in your call. 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

Note

Context and symptoms

Your API call 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 call.

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 OAuth2 token (see Get your Coveo access token).

403 - ACCESS_DENIED

Note

Context and symptoms

Your API call fails with a 403 ACCESS_DENIED error.

Likely cause and resolution

Cause

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

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)

Note

Context and symptoms

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

  • The API call 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

Note

Context and symptoms

Your API call 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 number of Push API operations in a single batch (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

Note

Context and symptoms

Your API call fails with a 412 DOCUMENT_LIMIT_EXCEEDED error.

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

Note

Context and symptoms

Your API call 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 call is invalid.

Resolution

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

412 - MISSING_PARAMETER

Note

Context and symptoms

Your API call 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 call.

Resolution

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

412 - SOURCE_DOES_NOT_EXIST

Note

Context and symptoms

Your API call 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 call.

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

Note

Context and symptoms

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

Likely cause and resolution

Cause

You’re trying to perform a push operation whose total size exceeds the allowed limit (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 call (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

Note

Context and symptoms

Your API call fails with a 415 UNSUPPORTED_MEDIA_TYPE error.

Likely cause and resolution

Cause

You’re trying to make a Push API call 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 call.

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

429 - TOO_MANY_REQUESTS

Note

Context and symptoms

Your API call fails with a 429 TOO_MANY_REQUESTS error.

Likely cause and resolution

Cause

  • A possibility is that you have exceeded one of your daily Push API limits (that is, your number of daily Push API calls) with the number of items processed daily by the Push API, or the number of security identities processed daily by the Push API. You can see whether this is the case by reviewing your current usage of your organization 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 daily Push API limits, wait until the limit resets, that is, until midnight UTC, and ensure you respect those limits going forward. We recommend that you implement an exponential backoff strategy to retry your calls after a certain amount of time.

  • If you have not exceeded one of your daily Push API limits, wait until your calls are no longer being throttled before using the service again. In the future, ensure that you make Push API calls at a slower pace, especially after a period of inactivity (see Push API Limits - Recommended Maximum Number of Items/Security Identities per Hour).

5XX

Note

Context and symptoms

Your API call 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 (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 operation 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

Note

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 Content 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

Note

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

Note

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 Source Status POST request to set the source status to REBUILD.

  2. Once the source shows as Retrieving content, perform another Source Status POST request to set the source status back to IDLE.

  3. After a few minutes, the source will be back to idle and showing Ready to receive content.

SSL connection issue with the C# Platform SDK

Note

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

Note

Context and symptoms

Likely cause and resolution

Cause

You provided orderingId values on add, update, or delete operations 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 calls where the Coveo service automatically sets its value to the current 13-digit number of milliseconds since Unix Epoch.

If you need to use the DELETE olderthan API request, you can inspect an item to find its orderingId value.

Delete older than operation doesn’t delete items

Note

Context and symptoms

Likely cause and resolution

Cause

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

Resolution

Perform the DELETE olderthan API 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.