A media workflow needs a path for requests that do not produce a file. The useful response depends on why the job stopped: a removed source, a temporary interruption and an invalid storage permission call for different actions.
Tornado records job status and, when available, a reason you can inspect in the dashboard or API. Use that evidence before submitting the same request again.
Start with the recorded outcome
Open the job in Jobs, or read it through the status endpoint. Keep the job ID with the source and options you submitted. Where a structured failure message is present, use it to explain the result to your own user.
A warning can describe a source that could not be accessed or processed under the requested conditions. The word “warning” does not mean that a complete file was delivered. Likewise, “Video unavailable” alone does not establish that someone deleted the source. If an older job has no recorded reason, say that the reason is unavailable rather than inventing one.
| What you see | What to check next |
|---|---|
| Pending or processing | Keep the job ID and wait within your application's deadline. |
| Source unavailable or restricted | Check that the source is accessible for the requested use. Repeating the same request may not help. |
| Processing or temporary service failure | Inspect the recorded reason and decide whether a bounded retry is appropriate. |
| Storage or upload failure | Check the destination and its credentials or permissions before retrying. |
| Completed, but a link does not open | Check link validity and destination read access before recreating the media. |
| Completed, but your app received no event | Read the job status and investigate webhook delivery separately. |
Decide whether a retry changes anything
If a source has been removed or requires access that is unavailable, a new request cannot make it accessible. Tell your user what is known and let them choose another source or correct the access conditions.
If the destination configuration is wrong, repair it and verify it with a small job. Confirm which API key or selected destination the request uses. Correcting a different storage configuration will not repair the original path.
For a temporary interruption, a bounded retry can make sense. Add waiting time between attempts and a final outcome when your own retry budget is exhausted. Keep both the original job ID and any new job ID returned by the retry operation.
Avoid immediately recreating a job just because your client timed out. A request may have been accepted before the connection broke. Reconcile the known job or recent submissions first so that a transport problem does not silently become duplicate work.
Handle final states explicitly
An API client should distinguish a successful Completed job from other final outcomes, including Failed, Warning, Skipped, Cancelled and CancelledByAdmin. Stop normal progress polling for those outcomes and route them to the appropriate action in your application.
Cancellation is a request to stop unfinished work. It does not undo a file already delivered, and it does not establish that the final job was unbilled. Read the resulting state and usage instead of treating a button click as confirmation of cancellation.
Make webhook recovery part of the integration
Webhooks connect the outcome to your application without continuous polling. Configure the event contract for your integration and return a successful response after your receiver has durably accepted the event. Process lengthy downstream work separately.
Make the receiver tolerate repeated notifications so a retry does not trigger duplicate publishing or processing. When webhook signing is configured, verify the signature according to the webhook documentation.
Notification retries are bounded. If your receiver is unavailable long enough, recover by looking up the job status. A successful media job remains a successful media job even if delivery of its notification needs attention.
Give support a reproducible case
Include the job ID, approximate time, source type, requested output and the recorded message. Explain whether the problem affects one source or several, and whether it occurs before completion or when opening the file. Keep API keys, signed links and storage secrets out of public reports.
For a wider disruption, consult service status and contact support with those details. Use the storage guide when the remaining problem is access to an already delivered file.