video-captions alignment_reason: the six values explained

When a script_text caption job fails alignment, the error details may include an alignment_reason plus the script and STT word counts. The six documented values are invalid_alignment_payload, empty_aligned_words, invalid_stt_span, overlapping_stt_spans, non_monotonic_timings and script_coverage_mismatch.

What the details contain

The OpenAPI schema says these details are public-safe: the reason and the word counts only, never the script text, STT word text or raw model payloads. Compare script_word_count with stt_word_count first. A large gap points at a script that does not match what was said.

The documented fix

The docs list script_alignment_mismatch and script_alignment_failed as the public error codes and suggest the next action simplify_script_text_or_omit. Omitting script_text burns the STT wording instead. The reasons in the middle column are descriptions of the names, not guarantees, since the docs do not explain each one.

A practical order

First check the video has audible speech, because silent clips fail as caption_no_speech. Then shorten or simplify the script so it matches the spoken words. If it still fails, drop script_text and, if the wording matters, supply authored cues instead. The mismatch fix post covers the common case.