--- title: Troubleshoot UA Write API error codes slug: '1431' canonical_url: https://docs.coveo.com/en/1431/ collection: build-a-search-ui source_format: adoc --- # Troubleshoot UA Write API error codes This article explains why you may be getting certain error codes when using the [Usage Analytics (UA) Write API](https://docs.coveo.com/en/18/), 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: ```json { "message": "", "type": "" } ``` Where: * `` (string) often contains helpful information about what precisely went wrong in your request. **Example** ```json "message": "Unable to parse the provided JSON: Unexpected character ('\"' (code 34)): was expecting comma to separate Object entries at line 2, column 24." ``` * `` (string) provides a more general indication of what went wrong in your request. **Example** ```json "type": "InvalidJson" ``` ## 400 BAD_REQUEST ### `InvalidHeadersException` **Symptom** The UA Write API returns a JSON containing the following: ```json "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](https://docs.coveo.com/en/1373/)). ### `InvalidJson` **Symptom** The UA Write API returns a JSON containing the following: ```json "type": "InvalidJson" ``` **Cause** The body of your call may be incorrectly formatted. The error message is typically quite precise: **Example** ```json "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: ```json "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](https://docs.coveo.com/en/1373/)). ### `InvalidToken` **Symptom** The UA Write API returns a JSON containing the following: ```json "type": "InvalidToken" ``` **Cause** The [Coveo Platform](https://docs.coveo.com/en/186/) 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](https://docs.coveo.com/en/123/) or [Renew Expired Search Tokens](https://docs.coveo.com/en/56#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](https://docs.coveo.com/en/228/). ### `InvalidTokenHeader` **Symptom** The UA Write API returns a JSON containing the following: ```json "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 `, where `` is your access token. ### `MissingParameter` **Symptom** The UA Write API returns a JSON containing the following: ```json "type": "MissingParameter" ``` **Cause** The body of your call may lack certain required key-value pairs. The error message is typically quite precise: **Example** ```json "message": "Parameter 'customEvent.eventType' is missing." ``` **Resolution** Ensure that your request body contains all of the required properties for the category of [Coveo Analytics event](https://docs.coveo.com/en/260/) that you're [attempting to log](https://docs.coveo.com/en/1373/). ### `NoWorkgroupAssociatedWithToken` **Symptom** The UA Write API returns a JSON containing the following: ```json "type": "NoWorkgroupAssociatedWithToken" ``` **Cause** The access token you're using isn't associated with any [Coveo organization](https://docs.coveo.com/en/185/). Most of the time, this error occurs when authenticating with an Oauth2 token which, unlike API keys and [search tokens](https://docs.coveo.com/en/1346/), 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: ```json "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** ```json "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](https://docs.coveo.com/en/56#request-a-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: ```json "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](https://docs.coveo.com/en/1707#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: ```json "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](https://platform.cloud.coveo.com/docs?api=UsageAnalyticsWrite). ## 406 NOT_ACCEPTABLE ### `InvalidRequest` (406) **Symptom** The UA Write API returns a JSON containing the following: ```json "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: ```json "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: ```json "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](https://docs.coveo.com/en/187/), see [JavaScript Search Framework Usage Analytics](https://docs.coveo.com/en/365/). If you're using the UA Write API directly, see [Log Usage analytics events](https://docs.coveo.com/en/1373/). ## 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](http://status.cloud.coveo.com).