Erro 153 ao incorporar um vídeo do YouTube: por que acontece e como corrigir

O erro 153 aparece quando o player do YouTube não sabe qual site o incorporou, porque falta o cabeçalho Referer. A correção para sites, WebViews e apps.

Você incorpora um vídeo do YouTube, o player carrega e, no lugar do vídeo, aparece uma caixa preta com “Error 153. Video player configuration error” (erro 153, erro de configuração do player de vídeo), muitas vezes com um link “Assistir no YouTube”. O vídeo está ok e o código de incorporação também. O que falta é a informação de quem está incorporando.

A causa: o player não sabe qual site o incorporou

Os termos do YouTube para desenvolvedores são claros. A página Required Minimum Functionality diz que tudo o que usa o player incorporado, incluindo a IFrame Player API, precisa se identificar pelo cabeçalho HTTP Referer. Os navegadores normalmente mandam isso sozinhos; a página pede para não usar configurações que o suprimam e recomenda a política de referência strict-origin-when-cross-origin.

Quando o player carrega sem Referer, ou com um que não identifica um site, ele se recusa a tocar e mostra o erro 153. Desenvolvedores que depuraram o problema, como Simon Willison, chegaram exatamente nisso. A página do Google não cita o número 153, mas a correção que ela descreve é a que faz o erro sumir.

O que remove o Referer num site

  • Um cabeçalho Referrer-Policy com no-referrer ou same-origin. Alguns frameworks e configurações de segurança adicionam um por padrão; no caso do Willison, era o SecurityMiddleware do Django, que manda same-origin.
  • Uma meta tag no head da página: <meta name="referrer" content="no-referrer">.
  • Um atributo referrerpolicy no próprio iframe, às vezes colocado por um plugin de incorporação.
  • noreferrer numa janela aberta para hospedar o player, o que a página do YouTube pede para não fazer.

A correção num site

Mande a política que o YouTube recomenda, como cabeçalho:

Referrer-Policy: strict-origin-when-cross-origin

ou como meta tag, se você não puder mudar os cabeçalhos:

<meta name="referrer" content="strict-origin-when-cross-origin">

Depois confira se nada mais específico sobrescreve: remova o atributo referrerpolicy do iframe ou deixe com o mesmo valor. Essa política manda só a sua origem (por exemplo https://exemplo.com.br) para outros sites, nunca o caminho completo, então você não abre mão de privacidade relevante. O Willison também notou que trocar a incorporação para youtube-nocookie.com só ajudou às vezes; o que resolveu foi corrigir a política.

A correção dentro de um app (WebView, Electron, Tauri)

Apps esbarram nisso com mais frequência, porque as páginas deles não vêm de um site. Uma página carregada de um arquivo local ou de um esquema próprio (file://, app://, tauri://localhost) não tem uma origem web para mandar, então o player não recebe um Referer que sirva. A página do YouTube lista o que fazer em cada plataforma:

  • WebView mobile carregando HTML local: defina o parâmetro baseUrl, que define o Referer.
  • SFSafariViewController no iOS: ele não consegue definir um Referer, então use o parâmetro origin do player.
  • Apps de desktop: adicione o Referer como cabeçalho HTTP na requisição, ou configure a WebView para mandar um.

Uma última opção, quando você não controla os cabeçalhos da WebView: hospede num domínio https de verdade, seu, uma página pequena que incorpora o player, e mostre essa página no app. O player passa a ver o seu domínio como quem incorporou.

Como a gente esbarrou nisso

Fazemos o Webstarted Toolbox, um app de barra de menus feito com Tauri, e o widget Media dele toca vídeos do YouTube. A interface roda em tauri://localhost, que não é uma origem web válida, então um iframe direto de youtube.com/embed falhava com o erro 153 toda vez. Resolvemos com a última opção acima: o widget mostra uma página pequena hospedada no nosso próprio domínio https, que manda um Referer correto e incorpora o player. O vídeo continua vindo direto do Google para quem assiste; só essa página pequena passa pelo nosso servidor.

Se você só quer assistir ao vídeo

O erro está no site ou no app que incorporou o vídeo, não do seu lado. O link “Assistir no YouTube” toca o vídeo no youtube.com. Uma exceção para conferir: uma extensão do navegador ou uma configuração de privacidade que remove o Referer de todas as requisições tira o mesmo cabeçalho, e pode causar o erro 153 em sites bem configurados.

Fontes