Error Handling

Whenever the API is unable to process a call, it will return an error. This happens e.g. when required parameters are missing, when authentication fails or when parameters are out of bounds.

Error Messages

If an API call succeeds, it always returns data in the following structure (example with the xml output format):

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>ok</status>
  ...
</response>

If an API call fails, an error message is returned. Errors are always structured as follows:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <status>error</status>
  <code>ParameterInvalid</code>
  <title>Invalid Parameter</title>
  <message>video_key: Video with the key aT2u4xRa does not exist</message>
</response>

The error message has the following parameters:

status : string

Call execution status. Set to error if call has failed.

code : string

An error code.

title : string

Error title (short error description).

message : string

Detailed error description.

In addition to returning an error message, the API sets the HTTP Status Code of the call response to the error specific code, instead of the regular status 200 OK.

Errors Codes

Here is a full list of error codes that can be returned if an API call fails:

UnknownError
  • title: An Unknown Error occurred
  • HTTP Status: 400 Bad Request
InternalError
  • title: Internal Error
  • HTTP Status: 500 Internal Server Error
NotFound
  • title: Not Found
  • HTTP Status: 404 Not Found
NoMethod
  • title: No Method Specified
  • HTTP Status: 400 Bad Request
NotImplemented
  • title: Method Not Implemented
  • HTTP Status: 501 Not Implemented
NotSupported
  • title: Method or parameter not supported
  • HTTP Status: 405 Method Not Allowed
CallInvalid
  • title: Call Invalid
  • HTTP Status: 400 Bad Request
CallFailed
  • title: Call Failed
  • HTTP Status: 500 Internal Server Error
DatabaseError
  • title: Database Error
  • HTTP Status: 500 Internal Server Error
FileUploadFailed
  • title: File Upload Failed
  • HTTP Status: 400 Bad Request
ItemAlreadyExists
  • title: Item Already Exists
  • HTTP Status: 409 Conflict
PermissionDenied
  • title: Permission Denied
  • HTTP Status: 403 Forbidden
PreconditionFailed
  • title: Method Precondition Failed
  • HTTP Status: 412 Precondition Failed
ParameterMissing
  • title: Missing Parameter
  • HTTP Status: 400 Bad Request
ParameterInvalid
  • title: Invalid Parameter
  • HTTP Status: 400 Bad Request
ParameterEmpty
  • title: Empty Parameter
  • HTTP Status: 400 Bad Request
APIParameterEncodingError
  • title: Parameter Encoding Error
  • HTTP Status: 400 Bad Request
ParameterTypeEmpty
  • title: Parameter Type Error
  • HTTP Status: 400 Bad Request
ApiKeyMissing
  • title: User Key Missing
  • HTTP Status: 400 Bad Request
ApiKeyInvalid
  • title: User Key Invalid
  • HTTP Status: 400 Bad Request
DigestInvalid
  • title: Digest Invalid
  • HTTP Status: 400 Bad Request
FileSizeInvalid
  • title: File Size Invalid
  • HTTP Status: 400 Bad Request
TimestampMissing
  • title: Timestamp Missing
  • HTTP Status: 400 Bad Request
TimestampInvalid
  • title: Timestamp Invalid
  • HTTP Status: 400 Bad Request
TimestampExpired
  • title: Timestamp Expired
  • HTTP Status: 403 Forbidden
NonceMissing
  • title: Nonce Missing
  • HTTP Status: 400 Bad Request
NonceInvalid
  • title: Nonce Invalid
  • HTTP Status: 400 Bad Request
SignatureMissing
  • title: Signature Missing
  • HTTP Status: 400 Bad Request
SignatureInvalid
  • title: Signature Invalid
  • HTTP Status: 400 Bad Request