Customer Sign In


Error reporting


In most cases, playback of content involves a server that generates a playback URL that is then handed off to a media player on a user's computer or device. The client uses the URL to initiate playback of the content.

One challenge is that, because the end-user's device is using the URL to start playback, any problems with that URL are reported to the user's device. For example, if your server generated a playback URL with an invalid authorization token, playback would not be permitted, and the error message would be delivered to the user's device, making it difficult for you to become aware of the problem.

upLynk's push logs are one way to become informed of these types of errors, but log files are delivered minutes or even hours after events occur, during which time many of your users might be unable to play content. This document describes an optional error reporting facility you can use to receive near real-time feedback on problems such as invalid playback URLs.

To use the error reporting facility, you set up an HTTP URL (a web service endpoint) that upLynk can call when it detects a problem. The message from upLynk includes the same information from errors in push logs, but is delivered only a few moments after the problem happens. In this way you can more quickly become aware of an issue and minimize the impact it has on your users.

Request and response format

When the upLynk system detects an error that it can report to you, it initiates an HTTP POST request to a URL you provide in your account configuration in the CMS. The body of the POST is a JSON object that contains details of the error. For example, if you provided upLynk with the error reporting URL of, an error request would look something like:

Error reporting request example
POST /callback/path?name=xyz&p1=ok HTTP/1.1
Accept-Encoding: identity
Content-Length: 295
Content-Type: application/x-www-form-urlencoded
Connection: close
User-Agent: Python-urllib/2.7

{"code": 400, "msg": "Invalid auth token", "url": "",
 "ip": "", "owner": "735c56ea4014685bca74c0a375236cc5", "subtype": "web", "timestamp": 1356015370,
 "ua": "Mozilla/5.001 (windows; U; NT4.0; en-US; rv:1.0) Gecko/25250101"}

The server should reply with a simple HTTP 200 response - no response body is required, but the lack of an HTTP 200 response will be treated as an error and can result in the system deciding to not deliver error messages for awhile, so it is important that an HTTP 200 response be given, e.g.:

Error reporting response example
HTTP/1.0 200 OK
Content-length: 0
Connection: close

The parameters included in the JSON object from upLynk parallel those found in the push logs:

ownerThe owner (account) ID for which the error is being reported
subtypesystem component or area in which the error occurred. In the current implementation, will always be the string 'web' to denote web services and APIs.
urlthe URL that was requested that generated the error.
ipthe IP address of the client that sent the URL
codethe HTTP response error code (e.g. 404) generated as a result of the URL
uathe HTTP "User-Agent" request header sent in the request
msga short description of why an error occurred
timestampUnix timestamp (UTC time when the error occurred, in seconds since the epoch)

Enabling error reporting

By default error reporting via a callback URL is disabled. To enable it, log in to the upLynk CMS and select the gear tab at the top of the screen. From there, click on the Error Reporting subtab. Inside the Error Reporting pane is a field where you can specify the reporting callback URL for the upLynk system to use.

Note too the Test Settings button which you can use to verify that upLynk can successfully contact your URL. Once you have successfully tested your reporting URL, be sure to click Save.

Additional notes and policies

Please keep in mind the following when using error reporting:

  • Real-time error reporting is "best effort" only - delivery is throttled and some messages may be discarded if there are a large number of errors for your account. Additionally, the system does not attempt to retry sending an error report on failure.
  • If the system is unable to deliver messages to the URL you have specified, pending error messages will be discarded and the system may wait up to 2 minutes before attempting to deliver any new messages.
  • If you change the reporting URL (including setting the URL for the first time or removing the URL), it may take up to 2 minutes for all servers in the system to react to the change.
  • The upLynk system can notify you of errors only when it is able to detect that the error pertains to your account. For example, given the playback URL, nothing will play since it is an invalid playbackURL, but no error will be delivered to your reporting URL because there is nothing in the invalid playback URL hat the upLynk system can use to identify your account.