Handling Errors

The InsightIQ API uses standard HTTP response codes to indicate success or failure of a request.

Requests in the 2xx range indicate success.
4xx range indicate failure in the information provided (invalid credentials, missing params)
5xx range indicate an error with InsightIQ's servers (exceptional cases).

Error response object

Error responses will include detailed attributes to help you identify and resolve issues quickly.

Attribute	Description
`type`	Category of error
`error_code`	Specific error code to help you identify the error
`message`	Helpful, human-readable error (typically with a hint about how to resolve) description
`http_status_code`	HTTP status code of the response
`request_id`	Unique request ID for the API request (helpful in debugging and reporting the error to InsightIQ)

An example is,

{
  "error": {
    "type": "INVALID_REQUEST_PARAMETERS",
    "error_code": "incorrect_account_id",
    "message": "Requested account id does not exist",
    "http_status_code": 400,
    "request_id": "c748e69e-0794-443c-9e0e-dba952d0096f"
  }
}

The older parameters code and status_code are deprecated, and set to be removed from the response in a future version. Please make sure to migrate to error_code and http_status_code respectively, on or before 1 May 2022.

HTTP status codes andd Error types

The following table outlines the different error types you could get based on the status code in the HTTP response:

HTTP Status Code	Error `type`	Description
400	`INVALID_REQUEST_PARAMETERS`	The request is invalid.
401	`UNAUTHORIZED_REQUEST`	The request is unauthorized.
403	`FORBIDDEN_REQUEST`	The request is not allowed.
404	`RECORD_NOT_FOUND`	The requested record could not be found.
413	`REQUEST_TOO_LARGE`	The request size is larger than can be handled.
415	`UNSUPPORTED_MEDIA_TYPE`	The request has an unsupported content-type or content-encoding.
429	`RATE_LIMIT`	Rate limit breached.
500	`INTERNAL_SERVER_ERROR`	The server could not process the request.
503	`SERVICE_UNAVAILABLE`	The server or the application is down.
504	`REQUEST_TIMEOUT`	The server is taking too long to respond.

Common error codes

The following table outlines the different error_codes you could get based on the specific error with the API request:

`error_code`	Message
`incorrect_work_platform_id`	Requested workplatform id does not exist
`incorrect_work_platform_id_format`	Pass workplatform id in uuid format
`incorrect_work_platform_name`	Pass a valid workplatform name
`invalid_active_status`	Pass a valid status as boolean
`invalid_credentials`	Pass a valid client ID and secret
`invalid_data_format`	Request has incorrect data format for the event
`invalid_from_date_format`	Pass from_date in the YYYY-MM-DD format
`invalid_limit`	Pass a limit between 1 and 100
`invalid_offset`	Pass an offset between 0 and {number of items}
`invalid_product_type`	Request has incorrect product value, please pass one or more of {list of existing valid product values}
`invalid_to_and_from_date`	to_date cannot be lesser than from_date
`invalid_to_date`	to_date cannot be greater than today
`invalid_to_date_format`	Pass to_date in the YYYY-MM-DD format
`invalid_url`	Pass url in a valid https format
`missing_from_date`	Pass a valid from_date in the YYYY-MM-DD format
`missing_parameter`	Request has missing parameters, add {missing_parameter_name} and try again
`rate_limit_reached`	Too many requests made too quickly, please try again in a while
`invalid_filters_query`	Request has an invalid filter query, please pass a properly formatted query in filters
`empty_query_value`	Request has an empty value for {parameter_name}
`empty_query_array`	Request has an empty array for {parameter_name}
`invalid_query_param`	Request has an invalid query parameter {parameter_name}
`invalid\_{param_name}`	{parameter_name} in request does not support arrays, please repeat the request with one value at a time
`invalid_array_in_query`	Pass a properly formatted array in {parameter_name}
`invalid_operator_for\_{param_name}`	{parameter_name} does not support the given operator, please use one of {list of valid operators}
`incorrect_format`	Request has incorrect format value, please pass one or more of {list of format values}
`incorrect_type`	Request has incorrect type value, please pass one or more of {list of type values}
`invalid_api_path`	The path specified in request does not exist
`request_too_large`	Incoming request size is larger than supported by the server
`credentials_disabled`	These credentials have been disabled, please contact the InsightIQ team
`invalid_token`	The auth token in the request is invalid.
`service_unavailable`	Our servers are not available to process this request, please try again in a while
`request_timeout`	Our servers are taking too long to process this request, please try again
`incorrect_commenter_id`	Requested commenter id does not exist
`invalid_external_id`	External ID cannot be greater than 100 characters
`invalid_from_date`	from_date cannot be greater than today
`malformed_json`	The JSON body in the request is not formatted properly, please validate the body before retrying
`invalid_request_body`	The JSON body in the request is not valid for the given endpoint and operation, please validate the body before retrying
`corrupt_data`	Internal data for this resource is corrupted, please contact InsightIQ with the request details
`invalid_redirect_uri`	The redirect URI in the request is not supported
`query_array_limit_exceeded`	Request array for {parameter_name} has exceeded the limit, please send maximum {supported_number_of_items} items in a request
`server_error`	There was an error processing this request, please contact us with the request ID
`missing_to_date`	Pass a valid to_date in the YYYY-MM-DD format
`product_not_supported`	The product specified in the request is not supported for this account
`data_not_synced`	Data for this request is not synced yet, please check sync status of the account before trying again
`data_not_available`	Data for this request is not available, please contact us with the request ID

Debugging and Support

If you are still facing issues, please write to us with your request_id and other details at [email protected].

Was this helpful?