Qual limite de legenda do Instagram a API da Meta de fato aplica

Qual é o limite de legenda do Instagram na API?

A Meta escreve o limite de legenda do Instagram em uma única frase na referência do endpoint de criação de mídia: "Maximum 2200 characters, 30 hashtags, and 20 @ tags." Essa frase fecha a descrição do parâmetro de query caption em POST /<IG_ID>/media, e é o único lugar em que a Meta enuncia os três números juntos.

A descrição completa do parâmetro, citada como a Meta publica:

A caption for the image, video, or carousel. Can include hashtags (example: #crazywildebeest) and usernames of Instagram users (example: @natgeo). @Mentioned Instagram users receive a notification when the container is published. Maximum 2200 characters, 30 hashtags, and 20 @ tags.

Três tetos separados vivem nessa frase única, e eles falham de três jeitos diferentes. Dois devolvem erros documentados. Um não devolve.

Onde a legenda entra no fluxo de publicação?

A legenda vai no container, não na publicação. O fluxo de publicação de conteúdo do Instagram tem duas chamadas: POST /<IG_ID>/media cria o container e POST /<IG_ID>/media_publish publica. A chamada de publicação recebe creation_id e nada mais que toque em texto.

curl -X POST "https://graph.facebook.com/<LATEST_API_VERSION>/<IG_USER_ID>/media" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d "image_url=<IMAGE_URL>" \
  -d "caption=<CAPTION>"

Uma legenda longa demais portanto falha na criação do container, antes de qualquer mídia ser publicada e antes de gastar cota. Essa é a versão amigável da falha. Nada foi ao ar, nada foi consumido, e a cota móvel de publicação reportada pelo content_publishing_limit fica intocada, porque esse contador só se mexe no media_publish.

Carrosséis colocam a legenda em um lugar específico. A Meta anexa um aviso ao parâmetro caption: "Not supported on images or videos in carousels." A legenda pertence ao container de carrossel criado com media_type=CAROUSEL, e defini-la em um container filho não faz nada. O mesmo aviso aparece em location_id, então os dois campos seguem a mesma regra.

Stories são mais estranhos. A sintaxe de requisição da Meta para containers de story de imagem e de vídeo lista image_url ou video_url, media_type=STORIES, user_tags e access_token, e caption está ausente das duas. A tabela de parâmetros ainda descreve caption de forma genérica como "A caption for the image, video, or carousel", o que também não menciona stories em nenhum sentido. A Meta nem permite nem proíbe por escrito.

Que erro uma legenda longa devolve?

HTTP 400, código 36004, subcódigo 2207010. A referência de códigos de erro da Meta publica a mensagem ao usuário com os espaços de variável intactos:

The submitted image's caption was {submitted-caption-length} characters long. The maximum number of characters permitted for a caption is {maximum-caption-length}. Please submit media with a shorter caption.

A solução recomendada na mesma linha repete o teto: "The user exceeded the maximum amount of characters for a caption. Advise user to use a shorter caption. Maximum 2,200 characters, 30 hashtags, and 20 @ tags."

Duas coisas valem notar nesse erro. A mensagem interpola o máximo real em tempo de execução em vez de fixá-lo, o que significa que o número oficial chega até você na própria string de erro. E a redação diz "The submitted image's caption", mesmo que o mesmo parâmetro caption sirva a vídeos, reels e carrosséis. A Meta não generalizou a string para casar com o campo.

A formatação do número também difere entre as duas páginas. A referência do parâmetro escreve "2200 characters." A referência de códigos de erro escreve "2,200 characters." Mesmo número, duas grafias, o que é sinal confiável de que nenhuma fonte única gera as duas páginas.

O que acontece quando você passa de 20 marcações com @?

HTTP 400, código 100, subcódigo 2207040, com a mensagem "Cannot use more than {max-tag-count} tags per created media." A solução recomendada da Meta fornece o número que a mensagem deixa como variável: "The app user exceeded the maximum number (20) of @ tags. Advise user to use fewer @ tags."

Esse é o segundo dos três tetos, e é o que as pessoas alcançam sem querer. Uma legenda que credita um fotógrafo, um local, um stylist, três colaboradores e uma marca já está em oito menções antes de o texto começar. O teto conta marcações com @ dentro do texto da legenda, que é um mecanismo diferente do parâmetro user_tags, que posiciona nomes de usuário em coordenadas x e y sobre a imagem, e diferente ainda de collaborators, que a Meta limita separadamente em "up to 3 instagram usernames."

Menções também não são cosméticas. A Meta observa que "@Mentioned Instagram users receive a notification when the container is published", o que significa que o teto de 20 marcações é um teto de notificação tanto quanto de texto.

Existe erro para a 31ª hashtag?

A Meta não publica nenhum. O teto de 30 hashtags aparece na descrição do parâmetro caption e no texto da solução recomendada na linha do erro de tamanho de legenda, e em lugar nenhum da tabela de códigos de erro do Instagram existe uma linha para passar desse teto. Existe linha para legendas longas demais, linha para marcações com @ demais, linhas para quantidade de itens de carrossel, marcações de produto, tamanho de imagem, proporção e formato de vídeo. Hashtags não têm linha.

Esse silêncio deixa o comportamento genuinamente sem documentação. A Meta não diz se uma 31ª hashtag rejeita o container, é removida, ou publica e é ignorada pela busca. O número 30 é publicado. A consequência de passar dele não é.

Essa é a lacuna para contornar no planejamento em vez de no teste, porque a resposta honesta de engenharia é aplicar 30 no seu próprio compositor e nunca descobrir. Ele também está muito acima da contagem que faz algum bem, já que a faixa de hashtags que de fato move o engajamento no Instagram fica longe do teto.

Como o limite da API se compara ao que o app permite?

A Meta publica um limite de legenda e ele é o da API. A documentação para desenvolvedores informa 2.200 caracteres, 30 hashtags e 20 marcações com @ para o parâmetro caption. A documentação de ajuda da Meta para o app do Instagram não publica limite equivalente de caracteres de legenda, nem teto de menções no app, nem teto de hashtags no app que possa ser rastreado até uma página ativa da Meta.

Então a comparação que a maioria dos artigos faz, a de que a API "bate" com o app em 2.200 caracteres, é uma comparação entre um número documentado e um não documentado. O número 2.200 é real e tem fonte. O gêmeo dele dentro do app é folclore repetido tempo suficiente para parecer citação.

O mesmo padrão aparece no campo vizinho. A Meta documenta o teto de 1.000 caracteres do parâmetro alt_text na API de publicação e não publica limite para a caixa de texto alternativo dentro do app. Um lado do produto é especificado, o outro não.

Existe uma diferença de comportamento que é documentada, e ela favorece o app. Quebras de linha e espaçamento são tratados pelo compositor no app, enquanto a API aceita qualquer string que você envie, e é por isso que times que montam legendas por código acabam resolvendo como colocar espaços em uma legenda do Instagram por conta própria em vez de herdar isso da interface.

O que um validador de legenda deve checar de fato?

Quatro checagens cobrem tudo que a Meta documenta, e elas rodam antes da chamada de container em vez de depois do erro:

• Contagem de caracteres igual ou abaixo de 2.200, medida na string final depois de desfeita qualquer codificação de URL.
• Contagem de hashtags igual ou abaixo de 30, aplicada localmente porque a Meta não devolve erro para isso.
• Contagem de menções com @ igual ou abaixo de 20, batendo com o teto do 2207040.
• Legenda anexada ao container do carrossel, nunca a um filho do carrossel.

Trate 36004 e 2207040 como erros de quem chama e não como erros para repetir. Nenhum dos dois se resolve em uma segunda tentativa com a mesma carga, e um laço de repetição contra uma legenda de 2.400 caracteres vai queimar requisições até outra coisa quebrar.

Perguntas frequentes

Qual é o limite exato de legenda que a Meta publica?

"Maximum 2200 characters, 30 hashtags, and 20 @ tags", no parâmetro caption do endpoint POST /<IG_ID>/media. A referência de códigos de erro repete os mesmos números como "2,200 characters, 30 hashtags, and 20 @ tags."

Qual código de erro significa que a legenda estava longa demais?

Código 36004, subcódigo 2207010, devolvido como HTTP 400. A mensagem interpola tanto o tamanho enviado quanto o máximo, então o teto real volta no próprio erro.

Dá para definir uma legenda em uma imagem individual de carrossel?

Não. A Meta marca o parâmetro caption como "Not supported on images or videos in carousels." A legenda vai no container de carrossel criado com media_type=CAROUSEL.

Menções com @ em uma legenda notificam o usuário?

Sim. A Meta afirma que "@Mentioned Instagram users receive a notification when the container is published", o que liga o teto de 20 marcações a notificações e não só ao tamanho do texto.

O que acontece se você enviar 31 hashtags?

A Meta não diz. O teto de 30 hashtags está publicado na descrição do parâmetro, e a tabela de códigos de erro do Instagram não contém linha para passar dele, então o comportamento não tem documentação.

O app do Instagram aplica os mesmos 2.200 caracteres?

A Meta publica esse número só para a API. A documentação de ajuda dela não traz limite equivalente de caracteres de legenda para o compositor do app, então a alegação muito repetida de que os dois batem não pode ser rastreada até a Meta.

O que acontece quando uma legenda falha na criação do container?

O container de mídia nunca é criado, então nada é publicado e a cota de publicação registrada por content_publishing_limit fica intacta, porque esse contador só se move com media_publish. A falha acontece antes de qualquer mídia ir ao ar, o que a torna mais barata que uma falha mais adiante no fluxo. Corrigir a legenda e reenviar não custa nada além da própria nova tentativa.

Dá para colocar uma legenda em um container de Stories do Instagram?

A sintaxe de requisição que a Meta documenta para containers de story lista image_url ou video_url, media_type=STORIES, user_tags e access_token, e caption está ausente dessa lista. A descrição genérica do parâmetro caption cobre imagens, vídeos e carrosséis, mas não diz nada sobre stories em nenhum sentido. A Meta não permite nem proíbe por escrito uma legenda em um container de story.

O limite de 2.200 caracteres vale também para vídeos e reels, não só para fotos?

O parâmetro caption fica no mesmo endpoint POST /<IG_ID>/media independente do tipo de mídia, então os limites de 2.200 caracteres, 30 hashtags e 20 marcações valem para vídeos e reels do mesmo jeito que para imagens. O texto do erro ainda chama isso de "the submitted image's caption" mesmo quando o container guarda um vídeo, porque a Meta escreveu essa string pensando em imagens e nunca atualizou. O texto é inconsistente, a aplicação do limite não é.

Menções com @ em uma legenda são a mesma coisa que usuários marcados na imagem?

São dois mecanismos separados com dois limites separados. Menções com @ vivem dentro do texto da legenda e têm limite de 20, enquanto user_tags posiciona nomes de usuário em coordenadas x e y sobre a imagem e não tem limite publicado. Collaborators é um terceiro mecanismo, à parte, limitado a 3.