Errors

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

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.
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.
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.

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.
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
–	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 setting.
400	QUERY_ACCOUNT_UNAVAILABLE	Requested data source account can't be found. See exclude_unavailable_accounts 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	Attempt to use setting decode_json_fields failed.
–	URL_INCOMPLETE	Provided URL is missing query parameters.
–	URL_INVALID	Provided URL does not look like a fully qualified URL.
–	URL_TEAM_INVALID	Provided URL contains credentials that do not belong to 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.

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.

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": "https://supermetrics.com/docs/product-api-error-codes#api_key_invalid"
        }
    }
}

Error 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

• 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.

Resources

→ List of HTTP status codes »