Troubleshoot Push API Error Codes

This is for:

Developer System Administrator
In this article

This article explains why you may be getting certain error codes when using the Push API, and provides some of the most common ways to handle those errors.

400

INVALID_JSON

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 - DocumentBody).

    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 Using 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 Using 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 Using the compressedBinaryDataFileId Property).

ORGANIZATION_IS_PAUSED

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

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 an API key (see Create an API key) or a OAuth2 token (see Get your Coveo access token) with the required privileges (see Get the privileges of an access token).

INVALID_TOKEN

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 modify the API key accordingly or to create a new API key with the required privileges for you.

  • 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

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 probably doesn’t have the required privileges. Ask an administrator to modify the API key accordingly or to create a new API key with the required privileges for you.

  • If you’re using an OAuth2 token to authenticate your call, your identity probably doesn’t have the required privileges in the target Coveo organization, if not already done. Ask an administrator to grant you those privileges or to create an API key for you with the required privileges.

404

ERROR_DESERIALIZING_BATCH_DOCUMENT_FROM_S3

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

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.

INVALID_PARAMETER

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

MISSING_PARAMETER

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.

SOURCE_DOES_NOT_EXIST

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

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

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 Using the compressedBinaryDataFileId Property).

429

TOO_MANY_REQUESTS

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.

  • 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

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.