SDKs

In general, it's recommended to use our Bitmovin API SDKs when working with our API, which is available for the most used programming languages and drastically speeds up your development.

Allowed Request Methods

• POST - Creates a resource
• GET - Retrieves a resource or list of resources
• DELETE - Delete a resource

API Authentication

Every request sent to the Bitmovin API must contain your API Key. The key can be placed in the header or URL of the request. The name of the key has to be X-Api-Key. Additionally, you can change your default organization just for one request. Therefore the Organization id must be provided in the header as well

Example in Head

Response Format

Every response is contained in an envelope. This means that each response has a predictable set of attributes with which you can expect to interact.

General Response Envelope

The response envelope shown below is in MSON format.

## ResponseEnvelope (object)
+ requestId: `6d84e126-d10c-4e52-bbfb-bd4c92bc8333` (string, required) - Unique correlation id
+ status (enum[string], required) - Response status information
    + Members
        + `SUCCESS`
        + `ERROR`
+ data (object, optional) - Response information
+ more (object, optional) - Additional endpoint specific information

It contains four properties:

Messages

Messages are used in successful and error responses to communicate details about the workflow. The Message object contains information of a single message. The type of the message could be either, INFO, ERROR, WARNING, DEBUG or TRACE. Typically you will see INFO messages and some WARNING and ERROR. DEBUG and TRACE will only be shown, if enabled for your account, or on beta features. Message also includes an optional datetime that describes the creation time of the message in our system.

## Message (object)
+ date: `2016-06-25T20:09:23.69Z` (string, optional) - Timestamp when the message occured
+ id: `cb90b80c-8867-4e3b-8479-174aa2843f62` (string, required) - Id of the message
+ type (enum[string], required) - Message type
    + Default: `INFO`
    + Members
        + `INFO` - Message is informational
        + `ERROR` - Message is an error message
        + `WARNING` - Message is an error message
        + `DEBUG` - Message is for debug
        + `TRACE` - Message is for tracing
+ text (string, required) - Message text
+ field (string, optional) - Error belongs to request field
+ links (array[Link], optional) - Links for more infos
+ more (object, optional) - Service specific information

It contains seven properties:

The Link object is contained in the message and has basically two properties. The href which is an URL and the title which is the title of that URL.

## Link (object)
+ href (string, required) - URL
+ title (string, optional) - URL title

Success Response

A successful response derives from the general response envelope and further specifies the data property. The success response always has the status SUCCESS. The data property is further specified through the ResponseSuccessData object.

## ResponseSuccess (ResponseEnvelope)
+ status (enum[string], required) - Response status information
    + Members
        + `SUCCESS`
+ data (ResponseSuccessData, optional) - Response information

The ResponseSuccessData object specifies the data object of a successful response. It contains the result from the service specific endpoint and an array of messages as defined in the messages section. These messages contain detail information about the workflow. The ResponseSuccessData object is defined by the following MSON.

## ResponseSuccessData (object)
+ result (object, optional) - Service specific result
+ messages (array[Message], optional) - Service specific messages

It contains two properties:

Error Response

The error response also derives from the ResponseEnvelope but further specifies the data property. Each error response has the status ERROR.

## ResponseError (ResponseEnvelope)
+ status (enum[string], required) - Response status information
    + Members
        + `ERROR`
+ data (ResponseErrorData, required) - Error information

The ResponseErrorData contains an error code as defined in the error code section. The response also contains a message as defined in the messages section. This message is intended to be shown to your users or in a frontend. An invidual message for a developer developerMessage that gives more details is also part of the ResponseErrorData. The developerMessage could be logged on the console or forwarded to your logging backend. Additionally the response could contain links why this error occured or how you could resolve such errors. Further detailed messages could also be part of the response, which show more details to trace error.

## ResponseErrorData (object)
+ code (enum[number], required) - Contains error codes as defined in error code section
+ message (string, required) - General error message
+ developerMessage (string, required) - Developer message
+ links (array[Link], optional) - Link for more infos
+ details (array[Message], optional) - Error details

ResponseErrorData contains the following properties:

Server Responses

• 200 OK - The request was successful (some API calls may return 201 instead).
• 201 Created - The request was successful and a resource was created.
• 202 Accepted - The request has been accepted for processing, but the processing has not been completed.
• 204 No Content - The request was successful but there is no representation to return (that is, the response is empty).
• 400 Bad Request - The request could not be understood or was missing required parameters.
• 401 Unauthorized - Authentication failed or user does not have permissions for the requested operation.
• 403 Forbidden - Access denied.
• 404 Not Found - Resource was not found.
• 405 Method Not Allowed - Requested method is not supported for the specified resource.
• 409 Conflict - Request could not be completed due to a conflict with the current state of the target resource.
• 429 Too Many Requests - Exceeded Bitmovin API limits. Pause requests, wait one minute, and try again.
• 503 Service Unavailable - The service is temporary unavailable (e.g. scheduled platform maintenance). Try again later.

API Error Codes

1XXX General Errors

• 1000 Missing attribute or field - Required attribute/field not valid or not present
• 1001 Parameter not valid - One or more parameters are not valid
• 1002 Invalid credentials - API key is not valid
• 1003 Unauthorized - You are not authorized to access this resource
• 1004 Undefined Error - An undefined error occurred and support should be contacted
• 1005 Request URL not valid - The requested URL does not match any available API resource
• 1006 Request method not valid - The HTTP method used is not supported for this URL

2XXX Encoding Errors

20XX General Encoding Errors

• 2000 Encoding resource error - General encoding resource error
• 2001 Input not valid - Input not valid
• 2003 Muxing error - Error during muxing
• 2004 Encryption error - Error during encryption
• 2005 Filter error - Error while applying filter
• 2006 Captions error - Error with specified captions
• 2007 Subtitle error - Error with specified subtitles
• 2008 Codec configuration error - Error with specified codec configuration
• 2009 Thumbnail error - Error while generating thumbnails
• 2010 Sprite error - Error while generating sprites
• 2011 Live error - Error during live streaming
• 2014 Demuxing error - Error while demuxing file
• 2015 Decoding error - Error while decoding file
• 2016 Encoding error - Error during encoding
• 2017 Upload error - Error while uploading files
• 2018 Internal error - Internal encoding error
• 2019 Infrastructure error - Error on the encoding infrastructure
• 2020 Invalid Encoder Version - The given encoder version is not available
• 2021 Delete not allowed - Deletion of encoding not allowed when status equals RUNNING or QUEUED
• 2022 Stop live encoding error - Error stopping the live encoder
• 2023 Live stream not ready - The live stream is preparing
• 2024 Stream input details not available - Stream input details not available
• 2025 Encoding configuration not valid - There is an error in the encoding configuration
• 2026 On Premise encoding not allowed - On Premise encoding not allowed for specific account
• 2027 Rescheduling failed - Rescheduling of an encoding to another infrastructure failed
• 2028 Wrong status for restarting live encoding - The live encoding could not be restarted because it is not in RUNNING or ERROR state
• 2029 Wrong encoding type - The specified encoding is not a live encoding
• 2030 Reprioritization not allowed - Reprioritization of encoding is not allowed, because it is already being processed
• 2039 Neither bitrate nor CRF are set - The video codec configuration is invalid. Either 'bitrate' or 'crf' must be set
• 2042 Could not access infrastructure - Kubernetes cluster or AWS account is offline / could not be accessed
• 2047 Encoding not started - Cannot retrieve encoding start request configuration, as the encoding has not been started yet

21XX Encoding Input Errors

• 2100 Input file not found - Could not find input file
• 2101 Bucket not found - Could not find input bucket
• 2102 Invalid file path - File path not valid
• 2103 Download access denied - File was not accessible
• 2104 Download timeout - File download timed out
• 2105 Download failure - File download failed
• 2106 Remote server problem - Remote server was not reachable
• 2107 Input file is not a valid media file - Encoder was not able to parse input file

22XX Encoding Output Errors

• 2200 Bucket not found - Could not find output bucket
• 2201 Invalid file path - File path not valid
• 2202 Upload access denied - Access denied during upload
• 2203 Upload timeout - File upload timed out
• 2204 Upload failure - File upload failed
• 2205 Remote server problem - Remote server was not reachable

23XX Encoding Codec Configuration Errors

• 2300 H264 configuration error - H264 configuration is not valid
• 2301 H265 configuration error - H265 configuration is not valid
• 2302 AAC configuration error - AAC configuration is not valid

24XX Encoding Filter Errors

• 2400 Watermark configuration not valid - Watermark configuration not valid
• 2401 Watermark encoding error - Error while applying watermark
• 2402 Crop configuration not valid - Crop configuration not valid
• 2403 Crop encoding error - Error while cropping
• 2404 Rotate configuration not valid - Rotate configuration not valid
• 2405 Rotate encoding error - Error while rotating frame

25XX Encoding Manifest Errors

• 2500 DASH manifest configuration not valid - DASH manifest configuration not valid
• 2501 HLS manifest configuration not valid - HLS manifest configuration not valid

26XX Encoding Transfer Errors

• 2600 Transfer configuration not valid - Transfer configuration not valid

7XXX Notification Errors

• 7000 Notification Error - General notification error

8XXX Limit Exceeded Errors

• 8000 Limit exceeded error - General limit exceeded error
• 8001 Limit reached for maximum encodings per month - Your account has reached the maximum number of encodings per month
• 8003 Limit reached for maximum bytes encoded - Your account has reached the limit of bytes it is allowed to encode
• 8004 Limit reached for maximum queued VOD encodings - Your account has reached the maximum number of queued VOD encodings
• 8005 Limit reached for maximum started LIVE encodings - Your account has reached the maximum number of queued or running live encodings
• 8006 Limit reached for maximum finished VOD encodings - Your account has reached the maximum number of free encodings
• 8007 Your account has been deactivated - Please contact support

API Rate Limits

Rate limiting of the Bitmovin API is on a per access token basis.

Ensure that you inspect the HTTP headers, as they provide information about the rate limits.