---
title: "Errors"
slug: "errors"
updated: 2025-12-10T12:25:07Z
published: 2025-12-10T12:25:07Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supermetrics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

Error responses consist of a [HTTP status code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) and a JSON error object in the response.

If HTTP status code is not specified in this page, it defaults to **500 Internal Server Error**. Requests that do not end with an error, respond with **2xx** HTTP status codes.

## Types of errors

### Authentication errors

| Status | Error | Description |
| --- | --- | --- |
| `401` | `ACCESS_TOKEN_INVALID` | Provided oAuth access token is either missing, invalid or expired |
| `401` | `API_KEY_INVALID` | Provided API key was invalid. |
| `401` | `API_KEY_REQUIRED` | No API key was provided for the request. See authentication for detailed instructions. |

### Access errors

| Status | Error | Description |
| --- | --- | --- |
| `403` | `ACCESS_DENIED_IP` | Access was denied due to IP restrictions in your API key. |
| `403` | `ACCESS_DENIED_PERMISSIONS` | Access was denied because your API key does not has sufficient permissions to access the resource. |
| `403` | `API_KEY_DISABLED` | Provided API key was valid but is no longer enabled. |
| `–` | `LICENSE_ACCESS_DATA_SOURCE` | Requested data source is not included in your license. |
| `403` | `LICENSE_ACCOUNT_LIMIT_EXCEEDED` | Request contains more accounts than your license allows. See [usage limits](/v1-api/apidocs/usage-limits#license-limits). |
| `429` | `LICENSE_DAILY_QUERY_LIMIT_EXCEEDED` | Your license has exceed that maximum amount of queries per day allowed for the data source. See [usage limits](/v1-api/apidocs/usage-limits#license-limits). |
| `403` | `LICENSE_EXPIRED` | Your license has expired. |
| `403` | `LICENSE_HISTORICAL_RANGE_EXCEEDED` | Request is asking for more historical days than your license permits. Historical days are the number of days between the oldest date in the request, and the current date, inclusive of future end dates. |
| `–` | `LICENSE_NOT_FOUND` | No license was found. Please contact support. |
| `403` | `LICENSE_QUERIES_SUSPENDED` | Your license queries have been suspended. Please contact support. |
| `403` | `LICENSE_ROW_LIMIT_EXCEEDED` | Request asks for more result rows with max_rows than your license permits. See [usage limits](/v1-api/apidocs/usage-limits#license-limits). |

### Request errors

| Status | Error | Description |
| --- | --- | --- |
| `400` | `ACCOUNT_FILTER_INVALID` | Provided account filter uses invalid data structure. |
| `400` | `ACCOUNT_FILTER_PATTERN_INVALID` | Filter pattern is not a PCRE compatible regular expression. |
| `400` | `ACCOUNT_ID_INVALID` | Provided value does not look like a valid account ID. |
| `400` | `ACCOUNT_REQUIRED` | Request requires one or more data source accounts. |
| `400` | `ACCOUNTS_INVALID` | Accounts are provided with invalid data structure. |
| `400` | `COMPARE_END_DATE_INVALID` | Provided comparison range end is not a valid date value. |
| `400` | `COMPARE_END_DATE_REQUIRED` | Request requires comparison range end date. |
| `400` | `COMPARE_DATE_RANGE_ORDER` | Requested comparison dates are reversed. |
| `400` | `COMPARE_SHOW_INVALID` | Requested display type for comparison values is invalid. |
| `400` | `COMPARE_START_DATE_INVALID` | Provided comparison range start is not a valid date value. |
| `400` | `COMPARE_START_DATE_REQUIRED` | Request requires comparison range start date. |
| `400` | `COMPARE_TYPE_INVALID` | Requested date range comparison type is invalid. |
| `400` | `DATA_SOURCE_INVALID` | Requested data source ID is invalid. |
| `400` | `DATE_RANGE_ORDER` | Requested date range dates are reversed. |
| `400` | `DATE_RANGE_TYPE_INVALID` | Requested date range type is invalid. |
| `400` | `DATA_SOURCE_USERS_INVALID` | Data source users are provided with invalid data structure. |
| `400` | `END_DATE_INVALID` | Provided date range end is not a valid date value. |
| `400` | `END_DATE_REQUIRED` | Request requires date range end date. |
| `400` | `FIELD_INCOMPATIBLE` | Requested field can't be used with the query. See description for details. |
| `400` | `FIELD_NAME_INVALID` | Provided custom field name is invalid. |
| `400` | `FIELD_NOT_FOUND` | Requested field can't be found. |
| `400` | `FIELD_SPLIT_INVALID` | Requested field has invalid split type. See [fields](/v1-api/apidocs/fields). |
| `400` | `FIELDS_INCOMPATIBLE` | Requested fields can't be used together. |
| `400` | `FIELDS_INVALID` | Requested field parameter structure is invalid. |
| `400` | `FIELDS_REQUIRED` | Request requires at least one field. |
| `400` | `FIELDS_REQUIRED_METRICS` | Request requires more metric fields than were provided. |
| `400` | `FILTER_STRING_INVALID` | Filter string can't be understood due to invalid syntax. |
| `400` | `ORDER_COLUMNS_INVALID` | Requested column order type is invalid. |
| `400` | `ORDER_SORT_INVALID` | Order sort direction is invalid. |
| `400` | `PARAM_TYPE_INVALID_JSON` | Request parameter *json* was provided, but it was not a valid JSON string. |
| `400` | `SEGMENTS_NOT_SUPPORTED` | Provided segments but segments are not supported in the data source. |
| `400` | `SETTING_CONFIG_INVALID` | Provided settings use invalid data structure. |
| `400` | `SETTING_KEY_INVALID` | Provided setting key is invalid. |
| `400` | `SETTING_OPTION_INVALID` | Provided setting value is not one of the supported values. |
| `400` | `SETTING_TYPE_INVALID` | Provided setting has a value with an invalid data type. |
| `400` | `START_DATE_FUTURE` | Requested date range starts in the future. |
| `400` | `START_DATE_HISTORICAL` | Requested date range starts before the earliest supported start date for the data source. |
| `400` | `START_DATE_INVALID` | Provided date range start is not a valid date value. |
| `400` | `START_DATE_REQUIRED` | Request requires date range start date. |
| `400` | `SYNC_TIMEOUT_EXCEEDED` | Requested amount of seconds to wait for results that exceeded the maximum allowed value. |

### Data source errors

| Status | Error | Description |
| --- | --- | --- |
| `400` | `ACCOUNT_FILTER_MATCHLESS` | Account filter did not match to any accounts. |
| `400` | `QUERY_ACCOUNT_INVALID` | Requested data source account is invalid, due to reason in the description. See [exclude_invalid_accounts](/v1-api/apidocs/accounts#related-settings) setting. |
| `429` | `QUERY_ACCOUNT_UNAVAILABLE` | Requested data source account can't be found. See [exclude_unavailable_accounts](/v1-api/apidocs/accounts#related-settings) setting. |
| `429` | `QUERY_API_RATE_LIMITED` | Data source API is rate limiting requests. Please allow some time to pass before retrying your request. |
| - | `QUERY_AUTH_EXPIRED` | Data source access token has expired and can't be automatically refreshed. |
| - | `QUERY_AUTH_FAILURE` | Login to data source failed. Please contact support. |
| - | `QUERY_AUTH_LOGIN_FAILED` | Data source authentication credentials are no longer valid. |
| - | `QUERY_AUTH_NOT_FOUND` | No suitable data source authentications found for request. |
| - | `QUERY_AUTH_UNAVAILABLE` | Requested data source authentication can't be found. |
| - | `QUERY_SEGMENT_UNAVAILABLE` | Requested data source segment can't be found. |

### Conversion errors

| Status | Error | Description |
| --- | --- | --- |
| - | `DECODE_JSON_FIELDS_FAILED` | Using the [decode_json_fields](/v1-api/apidocs/settings) setting was unsuccessful. |
| - | `URL_INCOMPLETE` | The given URL lacks some query parameters. |
| - | `URL_INVALID` | The provided URL does not appear to be a fully qualified URL. |
| - | `URL_TEAM_INVALID` | The supplied URL has credentials that are not associated with active authentication. |

### Queue errors

| Status | Error | Description |
| --- | --- | --- |
| - | `STATUS_NOT_FOUND` | Status for requested query could not be found. Either request is invalid, the query has not been registered yet, or the query status is no longer available. |
| `429` | `WORKFLOW_LISTENER_LIMIT_EXCEEDED` | You have exceeded the maximum amount of requests that can wait for the same query results. See [usage limits](/v1-api/apidocs/usage-limits#license-limits). |

### System errors

| Status | Error | Description |
| --- | --- | --- |
| – | `LOCK_TASK_NOT_FOUND` | Internal error while resolving already running query. Contact Supermetrics for support on this error. |
| – | `QUERY_ERROR` | Unknown error during query run. See description for details. |
| - | `*` | All other errors. |

## Error response

Detailed error information will be contained in one error object. Response can provide either an error or data, but never both.

### Error example

Following is an example of a full error response.

```plaintext
HTTP 401 Unauthorized
{
    "meta": {
        "request_id": "tDcBg85cRzVZru7mRVQNkQ35tE4DdsPu"
    },
    "error": {
        "code": "API_KEY_INVALID",
        "message": "Invalid API key",
        "description": "Provided API key was invalid."
    },
    "links": {
        "docs": {
            "href": "https://supermetrics.com/docs/product-api-error-codes#api_key_invalid"
        }
    }
}
```

### Error object properties

| Property | Type | Description |
| --- | --- | --- |
| `code` | `string` | Error code for the error |
| `message` | `string` | Short localized error message or code if not available |
| `description` | `string` | Detailed localized error description |
| `links` | `object` | Additional links for error, if available |
| `links > docs > href` | `string` | URL to relevant technical documentation |
| `links > help > href` | `string` | URL to relevant help to understand and/or resolve the error situation |

## Best practices

- Only reference the code property or HTTP status code to identify error situations in your application. Other properties can change at any time, or contain mixed dynamic information that cannot be guaranteed to be of consistent quality