YouTube upload failureReason: codec, tooSmall, emptyFile

When a YouTube API upload fails, the video resource's status.uploadStatus becomes failed and status.failureReason carries one of six values: codec, conversion, emptyFile, invalidFile, tooSmall or uploadAborted. Four of them can be caught before you upload by probing the file, and Sume's video inspect does that probe for free.

YouTube's side comes from the Videos resource and the videos.insert reference, read on 2026-10-02. Sume's side comes from video inspect and video trim.

What do the six failureReason values mean?

The Videos resource page gives one line for each. failureReason appears only when uploadStatus is failed. A separate rejectionReason appears when uploadStatus is rejected; that one spans copyright, policy, account and technical causes and is out of scope for a file check.

How do I probe a clip with Sume before uploading it?

Video inspect reads one clip on media.sume.com, so import the file first with POST /v1/media-imports. Pass frames: false for probe only; probe and stills are unbilled. The default mode is sync, which waits up to 30 seconds and returns 200 with the finished inspect, or 202 with a job to poll.

The resource carries a probe object, and probe.has_audio is the field Sume's docs name. We only rely on that one here; print the rest of the probe and compare it with what you intend to upload.

import hashlib, json, os, urllib.request

def probe(video_url):
    key = hashlib.sha256(video_url.encode()).hexdigest()[:24]
    req = urllib.request.Request(
        "https://api.sume.com/v1/video-inspect",
        data=json.dumps({"video_url": video_url, "frames": False}).encode(),
        headers={
            "Authorization": "Bearer " + os.environ["SUME_API_KEY"],
            "Content-Type": "application/json",
            "Idempotency-Key": "probe-" + key,
        },
    )
    with urllib.request.urlopen(req, timeout=40) as resp:
        return json.load(resp)

if __name__ == "__main__":
    url = "https://media.sume.com/artifacts/artf_demo/short.mp4"
    print(json.dumps(probe(url), indent=2))

What if the probe shows a problem?

If the encoding is the problem, video trim in its default exact precision re-encodes with libx264 and yuv420p, and keeps audio as AAC. Pass output with width, height and fps of 24, 25, 30 or 60 to conform the frame size and rate on the way out. Use a whole-clip range, starting at 0, to re-encode a clip you do not want shortened.

A trim costs $0.02 per job at the current public rate. Sume exposes no codec or bitrate fields; the server compiles the ffmpeg command and rejects vf, crf, codec and similar with ffmpeg_fields_rejected.

What can a pre-check not catch?

uploadAborted is a transfer problem. YouTube's upload guide uses resumable uploads with exponential backoff for exactly that, and ten retries in its sample. rejected uploads are decided on YouTube's side after processing. A clean probe lowers the odds of failed; it is not a guarantee of processed.

How do I use these values in a retry policy?

Treat the six values in two groups. emptyFile, invalidFile, tooSmall and codec describe the file, so retrying the same bytes will fail the same way: fix the file, then upload again. uploadAborted describes the transfer, so a retry of the same file is reasonable. conversion is the unclear one; the page gives no cause, so try one re-encoded copy before you give up.

Log the failureReason next to the Sume job that made the file. A pattern, such as every failure coming from one recipe, points at the recipe rather than at the network.

• codec, invalidFile, emptyFile, tooSmall: change the file.
• uploadAborted: retry the same file, using resumable upload.
• conversion: re-encode one copy and retry once.