Skip to content
Schedule Social Media
SchedulersNetworksAPI changesGuidesToolsCompareFind your schedulerNews

Press Esc to close.
Breaking YouTube Severity: low

YouTube caption track names are limited to 150 characters, longer names return nameTooLong

Announced12 Mar 2024
EffectiveNot stated
PlatformYouTube

What changed

YouTube's March 12, 2024 Data API revision updates the captions resource documentation to note that the maximum allowed length for snippet.name is 150 characters, and that the API returns a nameTooLong error if the track name is longer. The captions.insert reference lists nameTooLong as an invalidValue (400) error. The revision does not give a date when the limit started, so the effective date is not stated.

What it means

A captions.insert request with a track name over 150 characters fails with a nameTooLong error, so the caption upload does not happen.

Who is affected

Tools that upload caption or subtitle tracks to YouTube, including localisation and accessibility workflows.

What to do

Validate caption track names to 150 characters or fewer before calling captions.insert.

What this means for you

Captions are the words that show at the bottom of a video. Each set of captions has a name, like "English" or "Spanish (with sound effects)". YouTube only allows names up to 150 letters and spaces. If an app sends a longer name, YouTube refuses the captions.

The details

  • Field: snippet.name on the captions resource: "The name is intended to be visible to the user as an option during playback. The maximum name length supported is 150 characters."
  • Error: invalidValue (400), reason nameTooLong: "The snippet.name specified in the request is too long. The maximum length supported is 150 characters." It is listed on captions.insert; the captions.update reference does not list it.
  • Quota: captions.insert costs 400 units, and Google says invalid requests still cost at least 1 unit, so check the name before the call.
  • Related: since April 12, 2024 caption uploads must include timing information (our entry).
  • Not stated: when the limit started being enforced.

What to do next

  • Business owners: Nothing.
  • Marketers and agencies: Keep caption track names short, such as the language name.
  • Developers: Check snippet.name length (150 maximum) before captions.insert and handle nameTooLong.

Primary sources

Checked against the source 7 Nov 2026

Get an email when a new API change is added

Follow new entries with the RSS feed. Each platform also has its own feed, for example X or Meta.