Error Reference

This is a reference to errors returned by the Playback API.

Status codes and errors

Status Error Code Description
200 SUCCESS The normal response is sent.
400 BAD_REQUEST Mis-formatted request, i.e. duplicate query parameters supplied
401 INVALID_POLICY_KEY Must provide a BCOV-Policy header with a legal policy key.
403 ACCESS_DENIED, VIDEO_NOT_PLAYABLE, PLAYLIST_NOT_PLAYABLE, JWT_AUTH The policy key provided does not permit this account or video, or the requested resource is inactive. VIDEO_NOT_PLAYABLE can be returned from Roebuck by single video requests. It indicates that the video does not pass the playable check (ingested, active, in schedule).
404 VIDEO_NOT_FOUND, PLAYLIST_NOT_FOUND, RESOURCE_NOT_FOUND, ACCOUNT_NOT_FOUND The designated resource was not found.
405 METHOD_NOT_ALLOWED Only GET, HEAD and OPTIONS are allowed for this api.
500 SERVER_ERROR Internal Wedge server error, usually will have more information in the logs.
502 SERVER_ERROR, ACCOUNT_RETRIEVE_FAILURE, VIDEO_RETRIEVE_FAILURE, VIDEO_URLS_RETRIEVE_FAILURE, PLAYLIST_RETRIEVE_FAILURE, PLAYLIST_VIDEOS_RETRIEVE_FAILURE Got a bad response from a backend server, generally Roebuck or Nomic returned a 5xx error.
503 SERVICE_UNAVAILABLE Not returned by Wedge. Could happen if there were no active servers in the Load Balancer. That would be bad. (The Playerback API does not do rate limiting, nor do the services it calls.)
504 SERVER_TIMEOUT A call to a backend server or one of the servers they rely on timed out.

Error responses

As per the API design standards, error responses (4xx and 5xx) consist of an error response list of one or more maps that include an error_code, an optional error_subcode, and optionally a non-localized message with more details.

[{"error_code": "ERROR_CODE1"},
  {"error_code": "ERROR_CODE2", "message": "details can go here"}
  {"error_code": "ERROR_CODE3", "error_subcode": "MORE_SPECIFIC_CODE", "message": "human readable details about what happened"}]

Error codes

The error_code that is meant to be both human understandable and to be used by client code to choose different actions and translatable user messages. The error codes are UPPER_SNAKE_CASE.

Status Error Code Error Source
403 ACCESS_DENIED Nomic policy
403 VIDEO_NOT_PLAYABLE Roebuck
404 VIDEO_NOT_FOUND Roebuck
other VIDEO_RETRIEVE_FAILURE if could not retrieve video Roebuck
other VIDEO_URLS_RETRIEVE_FAILURE if could not retrieve sources or images Roebuck

Error subcodes

Here are some but not all of the error subcodes (search for :error_subcode in the source)

Error Code Error Subcodes
BAD_REQUEST DUPLICATE_PARAMETERS
ACCESS_DENIED POLICY_ERROR
ACCESS_DENIED ACCOUNT_ID, VIDEO_ID, CLIENT_GEO, CLIENT_IP, DOMAIN, POLICY_ERROR [1]
SOURCES_RESTRICTED TVE_AUTH
SERVER_ERROR LOOKUP_GEO
SERVER_TIMEOUT LOOKUP_GEO

Notes

[1] ACCESS_DENIED/POLICY_ERROR means any unexpected error while evaluating the Policy (including getting the video info for geo restricted accounts). It may be worth checking for exceptions in the log with this error.