Troubleshoot UA Write API error codes

This is for:

Developer

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

Error response body structure

When the UA Write API service is processing your request and encounters an error, it sends back a response with the following structure:

{
  "message": "<message>",
  "type": "<type>"
}

Where:

  • <message> (string) often contains helpful information about what precisely went wrong in your request.

Example
"message": "Unable to parse the provided JSON: Unexpected character ('\"' (code 34)): was expecting comma to separate Object entries at line 2, column 24."

  • <type> (string) provides a more general indication of what went wrong in your request.

Example
"type": "InvalidJson"

400 BAD_REQUEST

InvalidHeadersException

Symptom

The UA Write API returns a JSON containing the following:

"type": "InvalidHeadersException"

Cause

The header you’re sending may not be properly formatted (for example, one of the header values may not be of the right type).

Resolution

Ensure that your header values are properly formatted (see Log Usage analytics events).

InvalidJson

Symptom

The UA Write API returns a JSON containing the following:

"type": "InvalidJson"

Cause

The body of your call may be incorrectly formatted. The error message is typically quite precise:

Example
"message": "Unable to parse the provided JSON: Unexpected character ('\"' (code 34)): was expecting comma to separate Object entries at line 2, column 24."

Resolution

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

InvalidObject

Symptom

The UA Write API returns a JSON containing the following:

"type": "InvalidObject"

Cause

The body of your call may contain one or more properties whose specified value doesn’t match the format expected by the UA Write API. For example, specifying a string rather than an integer as an outcome value when logging a usage analytics event would produce and InvalidObject error.

Resolution

Ensure that your values have the correct type/format (see Log Usage analytics events).

InvalidToken

Symptom

The UA Write API returns a JSON containing the following:

"type": "InvalidToken"

Cause

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

Resolution

  • If you’re using an OAuth2 or search token to authenticate your call, this token may be expired. Try again using a fresh token (see, respectively, Get your Coveo access token or Renew Expired Search Tokens).

  • 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 the key. Modify the API key accordingly, or create a new API key with the required privileges.

InvalidTokenHeader

Symptom

The UA Write API returns a JSON containing the following:

"type": "InvalidTokenHeader"

Cause

The token header you’re sending may not be properly formatted. For example, there may be a typo like Baerer.

Resolution

Ensure that your token header has the form Authorization: Bearer <token>, where <token> is your access token.

MissingParameter

Symptom

The UA Write API returns a JSON containing the following:

"type": "MissingParameter"

Cause

The body of your call may lack certain required key-value pairs. The error message is typically quite precise:

Example
"message": "Parameter 'customEvent.eventType' is missing."

Resolution

Ensure that your request body contains all of the required properties for the category of usage analytics event that you’re attempting to log.

NoWorkgroupAssociatedWithToken

Symptom

The UA Write API returns a JSON containing the following:

"type": "NoWorkgroupAssociatedWithToken"

Cause

The access token you’re using isn’t associated with any Coveo organization. Most of the time, this error occurs when authenticating with an Oauth2 token which, unlike API keys and search tokens, isn’t associated with a specific organization.

Resolution

Specify a valid value for the org query parameter, or use an access token that’s associated with an organization (that is, an API key or a search token).

UnauthorizedHub

Symptom

The UA Write API returns a JSON containing the following:

"type": "UnauthorizedHub"

Cause

Usually, this error occurs when you’re authenticating with a search token whose searchHub doesn’t match the value of originLevel1 in your request body. The error message is typically quite precise:

Example
"message": "You are not authorized to insert events in search hub 'ExternalSearch' since your token restricts you to search hub 'SupportHub'.",

Resolution

  • Ensure that the value of originLevel1 in your UA Write request matches the searchHub of your search token, or request a new search token with the appropriate searchHub.

  • Ensure that there aren’t any typos in the originLevel1 value you specified.

UnauthorizedOrg

Symptom

The UA Write API returns a JSON containing the following:

"type": "UnauthorizedOrg"

Cause

The access token that you’re using doesn’t grant sufficient privileges in the target Coveo organization.

Resolution

  • Ensure that your access token has the privileges required to log usage analytics events to the organization you specified. If you’re using an API key, make sure that it has the privilege to push analytics data to Coveo (that is, the Allowed access level on the Analytics data domain).

  • Ensure that there aren’t any typos in the organization ID you specified.

404 NOT_FOUND

InvalidUri

Symptom

The UA Write API returns a JSON containing the following:

"type": "InvalidUri"

Cause

The UA Write API endpoint that you’re trying to reach doesn’t exist. Most of the time, this error is due to a typo.

Resolution

Ensure that you’re using a valid endpoint.

406 NOT_ACCEPTABLE

InvalidRequest (406)

Symptom

The UA Write API returns a JSON containing the following:

"type": "InvalidRequest"

Cause

You’re trying to make a call using the wrong Accept type.

Resolution

Ensure that your Accept header value is set to application/json.

415 UNSUPPORTED_MEDIA_TYPE

InvalidRequest (415)

Symptom

The UA Write API returns a JSON containing the following:

"type": "InvalidRequest"

Cause

You’re trying to make a call using the wrong content type.

Resolution

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

429 TOO_MANY_REQUESTS

TooManyRequestsException

Symptom

The UA Write API returns a JSON containing the following:

"type": "TooManyRequestsException"

Cause

You’ve exceeded the maximum number of calls that you can make in a given amount of time. You’re most likely attempting to log far more usage analytics events than are required, or there may be an issue in your application which is causing it to log far more events than intended.

Resolution

Wait until your calls are no longer being throttled before using the service again. In the future, ensure that your application makes UA Write API calls at a more standard rate.

If you’re using the Coveo JavaScript Search Framework, see JavaScript Search Framework Usage Analytics. If you’re using the UA Write API directly, see Log Usage analytics events.

5XX

Symptom

The UA Write API returns an error message with a 5XX status code.

Cause

You’ve triggered an unhandled error, or there’s an issue with the UA Write service itself.

Resolution

  • If it’s obvious that you’re not responsible for the error, try performing the operation again (with an exponential backoff).

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