Skip to content

Developers

How can we help you?

← Go back

Status codes and errors

The Mediagenix On-Demand APIs return an appropriate HTTP status code for every request. The response body may also contain a message explaining the problem, but the status code and not the response body is what you should use to determine whether a request was successful or not.

2xx AKA success!

Mediagenix On-Demand APIs will return a 2xx status code for any type of request (GET, POST, PUT or DELETE) that is received, understood, accepted, and processed successfully. You should consider any request returning a 2xx status code to be successful.

Even though Mediagenix On-Demand APIs will return one of the different 2xx status codes depending on the action performed (see the examples below), you are advised not to couple your code to one of the specific types. Any 2xx code should be considered a successful request.

Common status codes:

  • 200 OK: Standard response for successful HTTP requests. Mediagenix On-Demand API’s will return this status code for successful GET and PUT requests.
  • 201 Created: The request has been fulfilled and resulted in a new resource being created. Mediagenix On-Demand API’s will return this status code for successful POST requests, except for the publication resource where a 202 status code is returned.
  • 202 Accepted: The request has been accepted for processing, but the processing has not been completed.
  • 204 No Content: The server successfully processed the request, but is not returning any content. Mediagenix On-Demand API’s will return this for successful DELETE requests; note that the deletion of title-group and title resources is handled asynchronously.
    • We’re currently reviewing whether to return 202 status code for DELETE requests on those resources.

4xx AKA the request failed and it’s probably your fault

The 4xx status code will be returned when the request cannot be processed because something is wrong with what you’re sending.

Maybe you didn’t authenticate properly, you’re trying to access a non-existent resource, or you’re trying to create a resource without providing all the required data. The response body will normally provide the reason for the request being rejected.

You’ll normally get these errors when developing your integration and testing our APIs. However, in production, if you use our APIs properly, these errors shouldn’t happen. If they do, there’s probably something wrong in the way you’re trying to use Mediagenix On-Demand API’s. Advice is given below on how to deal with errors.

Common status codes:

  • 400 Bad Request: The request cannot be fulfilled due to bad syntax. Maybe the body of your request is not a valid XML document.
  • 401 Authorization Required: The credentials used in the request are missing or invalid. Maybe you’re not using digest authentication properly or your credentials are wrong.
  • 404 Not Found: The resource can’t be found. The URL you’re using is wrong for some reason. Maybe you’ve got an old link of a resource that no longer exists.
  • 405 Method Not Allowed: the HTTP method is not appropriate. Not every resource support the four operations (GET, POST, PUT, DELETE), if you send a request to a resource that doesn’t support the operation you’re requesting you’ll get a 405.
  • 406 Not Acceptable: the Accept header that you sent (GET requests) is not supported. Make sure that your requests include a supported Accept header.
  • 415 Unsupported Media Type: the Content-Type header that you sent ( POST and PUT requests) is not supported. Make sure that your requests include a supported Content-Type header.
  • 422 Unprocessable Entity: the resource submitted in the request can’t be processed. You might be sending invalid attribute values or values that result in validation errors. Check the response body for more details.
  • 429 Too Many Requests: rate limiting is enabled and has been exceeded; use the Ratelimit-Reset response header to determine when to retry (its value is in seconds).

Note that the Mediagenix On-Demand API validates the file name for subtitle, image, rendition, and audio_track files. If the file name in a given request includes any of the restricted characters shown below, then the response body for the 4xx error will include the The request could not be processed by the server due to malformed syntax message:

  • &, $, +, ,,/,:,;,=,?,@,<,>,[,],{,},|,\,^,~,%,#,any whitespace character,(, and )

5xx AKA the request failed and it’s probably our fault

Note: When the Mediagenix On-Demand and Sequence applications are in maintenance mode then their APIs will return a 503 status code.

The 5xx status codes will be returned when your request is apparently valid, but some problem in the server prevented the request from being processed. Maybe some part of our infrastructure is temporarily down, there’s a bug, or there are connectivity issues.

These errors are infrequent but they can happen and you should be prepared to deal with them. Mediagenix On-Demand’s Support team is immediately notified of each occurrence of any of these errors so that they can take action as soon as possible.

Dealing with errors

Since the requests that you send can fail, your production code should be prepared to handle error scenarios gracefully.

All synchronous operations in the Mediagenix On-Demand APIs are atomic, meaning that each request is either completely processed or not processed at all. In any case, the system always stays in a consistent state. When one of our APIs returns a 4xx or a 5xx error, you can safely assume that nothing has been changed in the system.

If your integration processing includes several operations that need to be requested sequentially, and one of those operations returns an error, in general, you should not continue that processing. We also advise you to setup a logging and notification mechanism that will alert you when this happens so you can take the appropriate action.

When debugging a 4xx error you should check the specific status code along with the response body to understand what was wrong with the request that you sent. Looking at the documentation page for the specific resource and operation you’re performing can also help you debugging the error. Finally, if you don’t find the reason for the error, you can always get in touch with the Mediagenix On-Demand Support team or your TAM.

If what you’ve got is a 5xx error, even though the Mediagenix On-Demand Support team will be automatically notified of it, you should also get in touch with them. The more information you can provide about the failing request (e.g. URL, type of operation, body, time of the request, the X-Request-Id header value, etc.) the easier it will be for us to help you with the problem.

Some 5xx errors might be returned for transitory circumstances (high load in our servers, connectivity issues, etc.). In order to make your integration code more robust, you should implement a retry mechanism. Ideally your code should automatically retry any 5xx failing request a few times before giving up and notifying you.

Throttling

To help you throttle your requests, we expose the counters used to evaluate quota policies via HTTP header fields.

  • Ratelimit-Limit: the maximum number of allowed requests in the time window.
  • Ratelimit-Remaining: the number of remaining requests in the current window.
  • Ratelimit-Reset: the time remaining in the current window expressed in seconds.

Example: a successful response with the following fields

HTTP/1.1 200 OK
Content-Type: application/json
Ratelimit-Limit: 150
Ratelimit-Remaining: 100
Ratelimit-Reset: 200

Retrying

We kindly ask you to be reasonable when retrying. There’s no point in sending a huge amount of retries in a short period of time. We suggest to wait a few seconds between each retry.

One sensible approach would be to follow an exponential backoff strategy. For example, your code could perform a 1st retry 2 seconds after the first attempt, then a 2nd retry 4 seconds after, then a 3rd retry 16 seconds after and so on. With something like this, four retries should probably be enough. If after all the retries, you keep getting a 5xx error, then your code should give up, stop the processing and notify you.

Please note that you shouldn’t retry 4xx errors. Those are caused because something is wrong with the request, meaning that any retry will always fail again; the exception here is the 429 error where you should retry after the Ratelimit-Reset period has expired.

If you decide to implement a retry mechanism make sure to only do it for 5xx or 429 errors, and only use an exponential backoff strategy for 5xx errors.