Error response

Sometimes, when a client makes a request to a Vimond service, it may encounter an error response due to various reasons. For example, the user might not be authenticated, or the request itself could be invalid.

Error response structure

Typically, the Vimond service returns an error response in the following format:

{
  "errors": [
    {
      "title": "ASSET_NOT_FOUND",
      "detail": "The asset requested does not exist",
      "code": "2000"
    }
  ]
}

While the HTTP status code provides an initial indication of the error, the error response provides more insight into the failure. The error response comprises three fields:

title: The name of the error
detail: A brief description of the encountered problem.
code: An internal error code unique to each specific issue, facilitating robust error handling.

The following error codes and descriptions help developers handle and troubleshoot issues more effectively when interacting with the Vimond API

General errors

Code	Title	Description
0	UNKNOWN	Unknown error
1000	INVALID_AUTHENTICATION	Invalid authentication token
1001	MISSING_AUTHENTICATION	Missing authentication token
1002	INVALID_QUERY_PARAM	Empty or invalid query parameter
1003	INVALID_REQUEST_PARAM	Empty or invalid request parameter
1004	SERVICE_UNAVAILABLE	Could not reach external resources
1005	INTERNAL_ERROR	Internal server error
1006	INVALID_SUBPROFILE	Invalid subprofile token
1007	INVALID_TENANT	Invalid tenant
1008	RESOURCE_NOT_FOUND	The requested resource was not found
1009	UNAUTHORIZED_ACCESS	User lacks required admin access
1010	INVALID_REQUEST_BODY	Empty or invalid request body

Content discovery errors

Code	Title	Description
2000	ASSET_NOT_FOUND	The requested asset does not exist
2001	CATEGORY_NOT_FOUND	The requested category does not exist
2002	CONTENT_PANEL_NOT_FOUND	The requested content panel does not exist
2003	SHOW_NOT_FOUND	The requested show does not exist
2004	INVALID_SORT_PARAM	Invalid sort parameter
2006	EPG_IS_NOT_ENABLED	EPG is not enabled for the requested tenant
2007	EPG_DATE_IS_OUT_OF_BOUND	EPG date range for the requested tenant is out of the allowed window

Play service errors

Code	Title	Description
3000	ASSET_NOT_FOUND	The asset requested does not exist
3001	INVALID_LOCALES	Invalid locales provided via the Accept-Languages header
3002	MISSING_IP	The IP address associated with the request is missing or invalid
3003	MISSING_CONTENT_PACKAGE	The user lacks a valid subscription to access this asset (v1 of playback API only).
3003	MISSING_ENTITLEMENT	The user does not have valid access to watch this asset (this error is only for v2 of playback API, changed to better reflect the actual cause in the case of missing PPV entitlements as well)
3004	INVALID_GEO_LOCATION	The requested asset is not available in the user’s location.
3005	NO_STREAM_AVAILABLE	No stream available after applying request filters
3006	DEVICE_LIMIT_EXCEEDED	The user has exceeded the total number of allowed devices.
3007	INVALID_STREAM_PROFILE	The requested quality does not match defined qualities.
3008	UNSUFFICIENT_QUALITY_ENTITLEMENT	The asset has available streams, but the user lacks sufficient quality entitlements.
3009	FAILED_TO_FETCH_LOG_DATA_CONFIGURATION	Unable to retrieve log data configuration
3010	FAILED_TO_COMPUTE_LOG_DATA_CONFIGURATION	Failed to compute log data
3011	ANONYMOUS_IP_NOT_ALLOWED	The request IP address is associated with an anonymization service.
3012	BAD_STREAM	The stream is invalid or missing required configuration
3013	ASSET_NOT_STARTED	The asset playback has not started yet
3014	INVALID_DEVICE_INFORMATION	The provided device information was missing or not valid.
3015	INVALID_UNTIL_ENTITLEMENT_CLAIM	The ‘until’ claim in entitlement is malformed and does not follow the ISO8601 timestamp format.
3016	MALFORMED_ENTITLEMENTS_CLAIM	The ‘entitlements’ claim is malformed

Sub profile service errors

Code	Title	Description
4000	UNAUTHORIZED_READ	User does not have the required read access
4001	UNAUTHORIZED_WRITE	User does not have the required write access
4002	SUBPROFILE_NOT_FOUND	Unable to find the requested subprofile
4003	INVALID_SUB_PROFILE	Invalid subprofile in the request body
4004	ERROR_CREATING_TOKEN	Error occurred while creating a subprofile token.
4005	SUBPROFILE_ALREADY_EXISTS	A subprofile with the given ID already exists
4006	SUBPROFILE_LIMIT_EXCEEDED	User exceeded the maximum subprofile limit.
4007	SUBPROFILE_LIMIT_INVALID_CONFIG	Invalid subprofile max limit configuration

Playlist service errors

Code	Title	Description
5000	PLAYLIST_NOT_FOUND	The requested playlist does not exist
5001	PLAYLIST_NOT_VALID	Invalid playlist received
5004	MISSING_USER_INFO	Missing user information in the request

Viewing history service errors

Code	Title	Description
6000	VIEWING_HISTORY_NOT_FOUND	Viewing history for the required asset does not exist.

Player session service errors

Code	Title	Description
7000	MALFORMED_EVENT	Empty or malformed event
7001	EVENT_MISMATCH	The event does not match the request
7002	SESSION_KICKED	One or more sessions are not allowed to continue playing the stream
7003	FAILED_TO_FETCH_LOG_DATA_CONFIGURATION	Unable to retrieve log data configuration
7004	EXPIRED_LOGDATA	The log data has expired
7005	INVALID_LOGDATA	The log data is invalid
7006	VIEWINGSESSION_NOTFOUND	Unable to find the viewing session

Device Registration errors

Code	Title	Description
10001	USAGE_NOT_FOUND	The requested usage does not exist
10002	USAGE_REPORT_NOT_FOUND	Unable to find usages for the given user
10003	DEVICE_DENIED	The device does not meet the ruleset requirements
10004	DEVICE_NOT_FOUND	The requested device was not found
10005	RULESET_NOT_FOUND	The requested ruleset does not exist
10006	DEVICE_DELETION_DENIED	Deletion of the device was denied
10007	INVAILD_DEVICE	Device was invalid

These error codes provide valuable information to developers, enabling them to diagnose and handle errors effectively when integrating with Vimond services