Job lifecycle and errors

To better understand how the API works, it is necessary to explain how the lifecycle of a job works.

A job can have one of the following status:

Usually, the focus will be on jobs with a completed or failed status.

When the job has been completed, you can follow the instructions to download the result

In case of a failed job, you will get a failed status. It will furthermore have an errors key, where you can find a more detailed messages on what caused the job to fail. It should look similar to this:

{
    ... extra information ...
    "status": {
        "code": "failed",
        "info": "The file has not been converted due to errors."
    },
    "errors": [
        {
            "source": "input",
            "id_source": "bc6eb7a7-8c3b-49fe-9216-0eedb2e32361",
            "code": 17,
            "message": "File not found, reasons for this error could be: bucket has incorrect permissions, you sent invalid credentials, or the file is really not there"
        }
    ],
    "process": true,
    ... extra information ...
}

By default a job fails if there is an error with an input file or the conversion of one input fails. If you want to continue the job in these cases we offer two options to achieve this.
If you don't want to fail the job if parts ot the inputs can not be downloaded, set "fail_on_input_error": false.
If you don't want to fail the job on a conversion error, set "fail_on_conversion_error": false.

If you set either of these two options, your job can have warnings instead of errors. If the job does not produce any output it will fail with an according error message.

POST /v2/jobs HTTP/1.1
Host: https://api.api2convert.com
X-Oc-Api-Key: <your API key here>
Content-Type: application/json
{
    "input": [{
        "type": "remote",
        "source": "https://example-files.online-convert.com/audio/mp3/example.mp3"
    },
    {
        "type": "remote",
        "source": "https://some-invalid-url.com"
    }],
    "conversion": [{
        "target": "txt"
    },
    {
        "target": "aac"
    }],
    "fail_on_input_error": false,
    "fail_on_conversion_error": false
}

curl -X POST \
    https://api.api2convert.com/v2/jobs \
    -H 'cache-control: no-cache' \
    -H 'content-type: application/json' \
    -H 'x-oc-api-key: <your API key here>' \
    -d '{
            "input": [{
                "type": "remote",
                "source": "https://example-files.online-convert.com/audio/mp3/example.mp3"
            },
            {
                "type": "remote",
                "source": "https://some-invalid-url.com"
            }],
            "conversion": [{
                "target": "txt"
            },
            {
                "target": "aac"
            }],
            "fail_on_input_error": false,
            "fail_on_conversion_error": false
        }'

In this case the warnings in the job info look like this:

{
    ... extra information ...
    "status": {
            "code": "completed",
            "info": "The file has been successfully converted."
    },
    "errors": [],
    "warnings": [
        {
            "source": "input",
            "id_source": "acef976e-b232-4af0-8e54-d737dbaf9746",
            "code": 1,
            "message": "The file could not be downloaded. We are unable to resolve the host address or the host is unreachable."
        },
        {
            "source": "conversion",
            "id_source": "76a84db8-4b8f-43de-9c40-e1ed4f34029a",
            "code": 6004,
            "message": "Unfortunately we can not convert your file yet from your source file format to this target file format."
        }
    ],
    "process": true,
    ... extra information ...
}