Troubleshooting Push API Error Codes

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

Symptom

The Push API returns an error mentioning 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 are 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 Understanding Push Source Item Metadata).

  • If you are pushing an uncompressed item, ensure that the request body minimally includes the data key-value pair (see Using the data Property).
  • If you are 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 are 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

Symptom

The Push API returns an error mentioning ORGANIZATION_IS_PAUSED.

Cause

You are attempting to make a request against a Coveo Cloud organization that is currently inactive.

Resolution

Ensure that the organization is reactivated (see Status). Then, try pushing your items again.

401

UNAUTHORIZED

Symptom

The Push API returns an error mentioning UNAUTHORIZED.

Cause

You are 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 Creating an API Key) or a OAuth2 token (see Getting Your Coveo Cloud V2 Platform Access Token) with the required privileges (see Getting the Privileges of an Access Token).

INVALID_TOKEN

Symptom

The Push API returns an error mentioning INVALID_TOKEN.

Cause

The Coveo Cloud platform does not recognize the access token you are using to authenticate your Push API call.

Resolution

  • If you are using an API key to authenticate your call, this key may have been disabled or deleted in the target Coveo Cloud 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 are using an OAuth2 token to authenticate your call, this token may be expired. Try again using a fresh Coveo Cloud platform OAuth2 token (see Getting Your Coveo Cloud V2 Platform Access Token).

403

ACCESS_DENIED

Symptom

The Push API returns an error mentioning ACCESS_DENIED.

Cause

The access token you are using to authenticate your Push API call does not grant you sufficient privileges to perform the operation.

Resolution

  • If you are using an API key to authenticate your call, this API key probably does not 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 are using an OAuth2 token to authenticate your call, your identity probably does not have the required privileges in the target Coveo Cloud organization. Ask an administrator to grant you those privileges. Alternatively, the administrator could create an API key with the required privileges for you.

404

ERROR_DESERIALIZING_BATCH_DOCUMENT_FROM_S3

Symptom

The Push API returns an error mentioning ERROR_DESERIALIZING_BATCH_DOCUMENT_FROM_S3.

Cause

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

Resolution

  • Ensure your batch document is a valid JSON object.

  • Consider decreasing or splitting up the number of Push API operations in a single batch (see Managing Batches of Items in a Push Source).

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

412

SOURCE_DOES_NOT_EXIST

Symptom

The Push API returns an error mentioning SOURCE_DOES_NOT_EXIST.

Cause

The Coveo Cloud platform does not recognize 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 (see Retrieving the ID of a Source).

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

    Creating the very first source in a new Coveo Cloud 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.

MISSING_PARAMETER

Symptom

The Push API returns an error mentioning MISSING_PARAMETER.

Cause

You did not 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.

INVALID_PARAMETER

Symptom

The Push API returns an error mentioning INVALID_PARAMETER.

Cause

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

Resolution

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

413

Request Entity Too Large

Symptom

The Push API returns an error concerning mentioning Request Entity Too Large.

Cause

You are trying to perform a push operation whose total size exceeds the allowed limit (see Push API Limits - Request Size Limits).

Resolution

  • If you are 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 are pushing a batch of items whose total size exceeds 256 megabytes, try pushing smaller batches.
  • If you are 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

Symptom

The Push API returns an error mentioning UNSUPPORTED_MEDIA_TYPE.

Cause

You are trying to make a Push API call using the wrong content type.

Resolution

In most cases, ensure that you include the Content-Type: application/json HTTP header in your call.

The only exception is when you are uploading content to an AWS container (see Using the compressedBinaryDataFileId Property). In this specific case, you must include the Content-Type: application/octet-stream and x-amz-server-side-encryption: AES256 headers instead.

429

TOO_MANY_REQUESTS

Symptom

The Push API returns an error mentioning TOO_MANY_REQUESTS.

Cause

This error typically occurs 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 Cloud APIs, and it is 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.

Resolution

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

Symptom

The Push API returns an error number 5XX.

Cause

You have triggered an unhandled error, or there is an issue with the Push API service itself, or with AWS (see Error Handling Patterns in API Gateway and AWS Lambda).

Resolution

  • If you are getting a 502 Bad Gateway error, ensure that the documentId for the item is properly URL-encoded. Then, try again.
  • If you are obviously not responsible for the error, try performing the operation again (with an exponential backoff). AWS issues typically resolve themselves when given enough time.
  • You can monitor the status of the Coveo Cloud platform from status.cloud.coveo.com.