Overview of the error and warning system

When you send a job to the API, a lot of things happen behind the scenes: we get the input files, we validate them, we try to understand which kind of files they are and finally we start the conversion giving back to you the converted file(s).

During this process, something can go wrong either by your side (e.g. a wrong URL for a remote input or a password protected file) or by our side (e.g. we cannot convert yet a particular file format).

If an error condition is detected, the API reports it to you using the errors and warnings arrays inside the JSON responses. This means that for a single job you can receive more than one error or warning.

The errors are conditions that lead to a failed conversion.

The warnings are conditions that lead to a successful conversion but for some reason, it might not be as expected or contain minor issues.

Following is an example of a failed conversion with two input errors inside:

"status": {
        "code": "failed",
        "info": "The file has not been converted due to errors."
    },
"errors": [
    {
        "source": "input",
        "id_source": "4ebe940f-7e20-4b5e-9bc1-cdaa5675e3eb",
        "code": 401,
        "message": "The file could not be downloaded by our servers, because a password has been requested to access the data."
    },
    {
        "source": "input",
        "id_source": "ed5c51d7-a2d0-4a93-ac8f-8c58e4af604b",
        "code": 404,
        "message": "The file could not be downloaded by our servers. Please verify the link you have provided."
    }
]

Following is an example of a failed conversion with one conversion error inside:

"status": {
        "code": "failed",
        "info": "The file has not been converted due to errors."
    },
"errors": [
    {
        "source": "conversion",
        "id_source": "d9e5b86b-7faa-4048-8cdf-3593b1d3a8bd",
        "code": 6005,
        "message": "Your file is missing important meta data and we therefore can not convert it."
    }
]

As you can see, there are always four fields:

  • "source": can be either input or conversion
  • "id_source": contains the id of the input or the conversion it is referring to. You can find the details about the input or the conversion in the same JSON response
  • "code": a unique numerical error code. If you plan on automatically reacting to an error or a warning, you have to check the code, not the message, because this can change at any time, while the code will stay the same
  • "message": a human readable explanation of the received error code. Be aware that this message can change at any time in the future, so always use the code

By using these items, it should be easy for you to prepare your software to correctly react to warnings and errors.

results matching ""

    No results matching ""