Error response consists of a HTTP status code and of a JSON error object.

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.

Authentication errors
401ACCESS_TOKEN_INVALIDProvided oAuth access token is either missing, invalid or expired
401API_KEY_INVALIDProvided API key was invalid.
401API_KEY_REQUIREDNo API key was provided for the request. See authentication for detailed instructions.

Access errors
403ACCESS_DENIED_IPAccess was denied due to IP restrictions in your API key.
403ACCESS_DENIED_PERMISSIONSAccess was denied because your API key does not has sufficient permissions to access the resource.
403API_KEY_DISABLEDProvided API key was valid but is no longer enabled.
 –LICENSE_ACCESS_DATA_SOURCERequested data source is not included in your license.
403LICENSE_ACCOUNT_LIMIT_EXCEEDEDRequest contains more accounts than your license allows. See usage limits.
429LICENSE_DAILY_QUERY_LIMIT_EXCEEDEDYour license has exceed that maximum amount of queries per day allowed for the data source. See usage limits.
403LICENSE_EXPIREDYour license has expired.
403LICENSE_HISTORICAL_RANGE_EXCEEDEDRequest 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_FOUNDNo license was found. Please contact support.
403LICENSE_QUERIES_SUSPENDEDYour license queries have been suspended. Please contact support.
403LICENSE_ROW_LIMIT_EXCEEDEDRequest asks for more result rows with max_rows than your license permits. See usage limits.
Request errors
400ACCOUNT_FILTER_INVALIDProvided account filter uses invalid data structure.
400ACCOUNT_FILTER_PATTERN_INVALIDFilter pattern is not a PCRE compatible regular expression.
400ACCOUNT_ID_INVALIDProvided value does not look like a valid account ID.
400ACCOUNT_REQUIREDRequest requires one or more data source accounts.
400ACCOUNTS_INVALIDAccounts are provided with invalid data structure.
400COMPARE_END_DATE_INVALIDProvided comparison range end is not a valid date value.
400COMPARE_END_DATE_REQUIREDRequest requires comparison range end date.
400COMPARE_DATE_RANGE_ORDERRequested comparison dates are reversed.
400COMPARE_SHOW_INVALIDRequested display type for comparison values is invalid.
400COMPARE_START_DATE_INVALIDProvided comparison range start is not a valid date value.
400COMPARE_START_DATE_REQUIREDRequest requires comparison range start date.
400COMPARE_TYPE_INVALIDRequested date range comparison type is invalid.
400DATA_SOURCE_INVALIDRequested data source ID is invalid.
400DATE_RANGE_ORDERRequested date range dates are reversed.
400DATE_RANGE_TYPE_INVALIDRequested date range type is invalid.
400DATA_SOURCE_USERS_INVALIDData source users are provided with invalid data structure.
400END_DATE_INVALIDProvided date range end is not a valid date value.
400END_DATE_REQUIREDRequest requires date range end date.
400FIELD_INCOMPATIBLERequested field can't be used with the query. See description for details.
400FIELD_NAME_INVALIDProvided custom field name is invalid.
400FIELD_NOT_FOUNDRequested field can't be found.
400FIELD_SPLIT_INVALIDRequested field has invalid split type. See fields.
400FIELDS_INCOMPATIBLERequested fields can't be used together.
400FIELDS_INVALIDRequested field parameter structure is invalid.
400FIELDS_REQUIREDRequest requires at least one field.
400FIELDS_REQUIRED_METRICSRequest requires more metric fields than were provided.
400FILTER_STRING_INVALIDFilter string can't be understood due to invalid syntax.
400ORDER_COLUMNS_INVALIDRequested column order type is invalid.
400ORDER_SORT_INVALIDOrder sort direction is invalid.
400PARAM_TYPE_INVALID_JSONRequest parameter json was provided, but it was not a valid JSON string.
400SEGMENTS_NOT_SUPPORTEDProvided segments but segments are not supported in the data source.
400SETTING_CONFIG_INVALIDProvided settings use invalid data structure.
400SETTING_KEY_INVALIDProvided setting key is invalid.
400SETTING_OPTION_INVALIDProvided setting value is not one of the supported values.
400SETTING_TYPE_INVALIDProvided setting has a value with an invalid data type.
400START_DATE_FUTURERequested date range starts in the future.
400START_DATE_HISTORICALRequested date range starts before the earliest supported start date for the data source.
400START_DATE_INVALIDProvided date range start is not a valid date value.
400START_DATE_REQUIREDRequest requires date range start date.
400SYNC_TIMEOUT_EXCEEDEDRequested amount of seconds to wait for results that exceeded the maximum allowed value.
Data source errors
  –ACCOUNT_FILTER_MATCHLESSAccount filter did not match to any accounts.
400QUERY_ACCOUNT_INVALIDRequested data source account is invalid, due to reason in the description. See exclude_invalid_accounts setting.
400QUERY_ACCOUNT_UNAVAILABLERequested data source account can't be found. See exclude_unavailable_accounts setting.
429QUERY_API_RATE_LIMITEDData source API is rate limiting requests. Please allow some time to pass before retrying your request.
  –QUERY_AUTH_EXPIREDData source access token has expired and can't be automatically refreshed.
  –QUERY_AUTH_FAILURELogin to data source failed. Please contact support.
  –QUERY_AUTH_LOGIN_FAILEDData source authentication credentials are no longer valid.
  –QUERY_AUTH_NOT_FOUNDNo suitable data source authentications found for request.
  –QUERY_AUTH_UNAVAILABLERequested data source authentication can't be found.
  –QUERY_SEGMENT_UNAVAILABLERequested data source segment can't be found.

Conversion errors
  –DECODE_JSON_FIELDS_FAILEDAttempt to use setting decode_json_fields failed.
  –URL_INCOMPLETEProvided URL is missing query parameters.
  –URL_INVALIDProvided URL does not look like a fully qualified URL.
  –URL_TEAM_INVALIDProvided URL contains credentials that do not belong to active authentication.

Queue errors
  –STATUS_NOT_FOUNDStatus 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.
429WORKFLOW_LISTENER_LIMIT_EXCEEDEDYou have exceeded the maximum amount of requests that can wait for the same query results. See usage limits.
System errors
  –LOCK_TASK_NOT_FOUNDInternal error while resolving already running query. Contact Supermetrics for support on this error.
  –QUERY_ERRORUnknown 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.

Following is an example of a full error response.

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": ""

Error properties

codestringError code for the error
messagestringShort localized error message or code if not available
descriptionstringDetailed localized error description
linksobjectAdditional links for error, if available
links > docs > hrefstringURL to relevant technical documentation
links > help > hrefstringURL to relevant help to understand and/or resolve the error situation

Best practices

  • Please use only 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.


→ List of HTTP status codes »

Last updated 2023-08-16 UTC.