El límite de caption de Instagram que la API de Meta aplica de verdad

¿Cuál es el límite de caption de Instagram en la API?

Meta escribe el límite de caption de Instagram en una sola frase de la referencia del endpoint de creación de contenido: "Maximum 2200 characters, 30 hashtags, and 20 @ tags." Esa frase cierra la descripción del parámetro de consulta caption en POST /<IG_ID>/media, y es el único sitio donde Meta enuncia las tres cifras juntas.

La descripción completa del parámetro, citada tal como la publica Meta:

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.

Tres techos distintos viven en esa única frase, y fallan de tres formas distintas. Dos de ellos devuelven errores documentados. Uno no.

¿En qué punto del flujo de publicación va el caption?

El caption va en el contenedor, no en la publicación. El flujo de publicación de contenido de Instagram tiene dos llamadas: POST /<IG_ID>/media crea el contenedor y POST /<IG_ID>/media_publish lo publica. La llamada de publicación toma creation_id y nada más que toque 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>"

Un caption demasiado largo falla por tanto en la creación del contenedor, antes de que se publique ningún contenido y antes de gastar cuota. Esa es la versión amable del fallo. Nada ha salido en directo, nada se ha consumido y la cuota móvil de publicación que reporta content_publishing_limit queda intacta, porque ese contador solo se mueve en media_publish.

Los carruseles ponen el caption en un lugar concreto. Meta añade una advertencia al parámetro caption: "Not supported on images or videos in carousels." El caption pertenece al contenedor de carrusel creado con media_type=CAROUSEL, y fijarlo en un contenedor hijo no hace nada. La misma advertencia aparece en location_id, así que los dos campos siguen la misma regla.

Las historias son más raras. La sintaxis de petición de Meta para contenedores de historia de imagen y de vídeo enumera image_url o video_url, media_type=STORIES, user_tags y access_token, y caption no está en ninguna de las dos. La tabla de parámetros sigue describiendo caption de forma genérica como "A caption for the image, video, or carousel", que tampoco menciona las historias en ningún sentido. Meta no lo permite ni lo prohíbe por escrito.

¿Qué error devuelve un caption demasiado largo?

HTTP 400, código 36004, subcódigo 2207010. La referencia de códigos de error de Meta publica el mensaje de usuario con los huecos de variable 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.

La solución recomendada de esa misma fila repite el techo: "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."

Dos cosas merecen atención en ese error. El mensaje interpola el máximo real en tiempo de ejecución en lugar de fijarlo en el código, lo que significa que la cifra autorizada te llega en la propia cadena de error. Y la redacción dice "The submitted image's caption", aunque ese mismo parámetro caption sirve a vídeos, reels y carruseles. Meta no ha generalizado la cadena para que encaje con el campo.

El formato de los números también cambia entre las dos páginas. La referencia del parámetro escribe "2200 characters." La referencia de códigos de error escribe "2,200 characters." La misma cifra, dos escrituras, que es una señal fiable de que no hay una sola fuente generando ambas páginas.

¿Qué pasa si superas las 20 etiquetas @?

HTTP 400, código 100, subcódigo 2207040, con el mensaje "Cannot use more than {max-tag-count} tags per created media." La solución recomendada de Meta aporta el número que el mensaje deja como variable: "The app user exceeded the maximum number (20) of @ tags. Advise user to use fewer @ tags."

Este es el segundo de los tres techos, y es el que la gente alcanza sin querer. Un caption que acredita a un fotógrafo, un local, un estilista, tres colaboradores y una marca va ya por ocho menciones antes de que empiece el texto. El tope cuenta las etiquetas @ dentro del texto del caption, que es un mecanismo distinto del parámetro user_tags que coloca nombres de usuario en coordenadas x e y sobre la imagen, y distinto otra vez de collaborators, que Meta limita por separado a "up to 3 instagram usernames".

Las menciones tampoco son decorativas. Meta señala que "@Mentioned Instagram users receive a notification when the container is published", lo que significa que el tope de 20 etiquetas es un tope de notificaciones tanto como un tope de texto.

¿Hay un error para el hashtag número 31?

Meta no publica ninguno. El tope de 30 hashtags aparece en la descripción del parámetro caption y en el texto de la solución recomendada de la fila del error de longitud de caption, y en ninguna parte de la tabla de códigos de error de Instagram hay una fila por superarlo. Hay una fila para captions demasiado largos, una fila para demasiadas etiquetas @, filas para recuentos de carrusel, etiquetas de producto, tamaño de imagen, relación de aspecto y formato de vídeo. Los hashtags no tienen fila.

Ese silencio deja el comportamiento genuinamente sin documentar. Meta no dice si un hashtag número 31 rechaza el contenedor, se elimina o se publica y la búsqueda lo ignora. El número 30 está publicado. La consecuencia de pasarlo no.

Este es el hueco que conviene sortear en la planificación en vez de a base de pruebas, porque la respuesta honesta de ingeniería es aplicar 30 en tu propio compositor y no averiguarlo nunca. Además queda muy por encima del recuento que hace algún bien, ya que el rango de hashtags que de verdad mueve la interacción en Instagram está lejísimos del techo.

¿Cómo se compara el límite de la API con lo que permite la app?

Meta publica un límite de caption y es el de la API. La documentación para desarrolladores enuncia 2.200 caracteres, 30 hashtags y 20 etiquetas @ para el parámetro caption. La documentación de ayuda de Meta para la app de Instagram no publica ningún límite equivalente de caracteres de caption, ningún tope de menciones en la app y ningún tope de hashtags en la app que se pueda citar contra una página viva de Meta.

Así que la comparación que hacen la mayoría de los artículos, que la API "coincide" con la app en 2.200 caracteres, es una comparación entre una cifra documentada y una que no lo está. La cifra de 2.200 es real y tiene fuente. Su gemela dentro de la app es folclore repetido tanto tiempo que parece una cita.

El mismo patrón aparece en el campo vecino. Meta documenta el techo de 1.000 caracteres del parámetro alt_text en la API de publicación y no publica ningún límite para la caja de texto alternativo dentro de la app. Un lado del producto está especificado, el otro no.

Hay una diferencia de comportamiento que sí está documentada, y favorece a la app. Los saltos de línea y el espaciado los maneja el compositor de la app, mientras que la API toma la cadena que le envíes, y por eso los equipos que construyen captions de forma programática acaban resolviendo ellos mismos cómo poner espacios en un caption de Instagram en vez de heredarlo de la interfaz.

¿Qué debería comprobar un validador de captions?

Cuatro comprobaciones cubren todo lo que Meta documenta, y corren antes de la llamada al contenedor y no después del error:

• Recuento de caracteres igual o inferior a 2.200, medido sobre la cadena final después de deshacer cualquier codificación de URL.
• Recuento de hashtags igual o inferior a 30, aplicado en local porque Meta no devuelve ningún error por ello.
• Recuento de menciones igual o inferior a 20, en línea con el tope de 2207040.
• Caption adjunto al contenedor de carrusel, nunca a un hijo del carrusel.

Trata 36004 y 2207040 como errores del que llama y no como reintentables. Ninguno se despejará en un segundo intento con la misma carga, y un bucle de reintentos contra un caption de 2.400 caracteres quemará peticiones hasta que se rompa otra cosa.

Preguntas frecuentes

¿Cuál es el límite exacto de caption que publica Meta?

"Maximum 2200 characters, 30 hashtags, and 20 @ tags", en el parámetro caption del endpoint POST /<IG_ID>/media. La referencia de códigos de error repite las mismas cifras como "2,200 characters, 30 hashtags, and 20 @ tags".

¿Qué código de error significa que el caption era demasiado largo?

Código 36004, subcódigo 2207010, devuelto como HTTP 400. El mensaje interpola tanto la longitud enviada como el máximo, así que el techo real vuelve en el propio error.

¿Se puede poner un caption a una imagen concreta de un carrusel?

No. Meta marca el parámetro caption como "Not supported on images or videos in carousels". El caption va en el contenedor de carrusel creado con media_type=CAROUSEL.

¿Las menciones @ de un caption avisan al usuario?

Sí. Meta afirma que "@Mentioned Instagram users receive a notification when the container is published", lo que liga el tope de 20 etiquetas a las notificaciones y no solo a la longitud del texto.

¿Qué pasa si envías 31 hashtags?

Meta no lo dice. El tope de 30 hashtags está publicado en la descripción del parámetro, y la tabla de códigos de error de Instagram no contiene ninguna fila por superarlo, así que el comportamiento está sin documentar.

¿La app de Instagram aplica los mismos 2.200 caracteres?

Meta publica esa cifra solo para la API. Su documentación de ayuda no lleva ningún límite equivalente de caracteres de caption para el compositor de la app, así que la afirmación muy repetida de que ambos coinciden no se puede rastrear hasta Meta.

¿Qué pasa cuando un caption falla en la creación del contenedor?

El contenedor de medios nunca se crea, así que nada se publica y la cuota de publicación que registra content_publishing_limit queda intacta, porque ese contador solo se mueve con media_publish. El fallo ocurre antes de que cualquier medio salga a producción, lo que lo hace más barato que un fallo más adelante en el flujo. Corregir el caption y reenviarlo no cuesta nada más allá del propio reintento.

¿Se puede poner un caption en un contenedor de Stories de Instagram?

La sintaxis de solicitud que Meta documenta para los contenedores de Stories enumera image_url o video_url, media_type=STORIES, user_tags y access_token, y caption no aparece en esa lista. La descripción genérica del parámetro caption cubre imágenes, videos y carruseles, pero no dice nada sobre Stories en ningún sentido. Meta ni permite ni prohíbe por escrito un caption en un contenedor de Stories.

¿El límite de 2.200 caracteres se aplica también a videos y reels, no solo a fotos?

El parámetro caption vive en el mismo endpoint POST /<IG_ID>/media sin importar el tipo de medio, así que los límites de 2.200 caracteres, 30 hashtags y 20 etiquetas se aplican igual a videos y reels que a imágenes. El texto del error sigue llamándolo "the submitted image's caption" incluso cuando el contenedor guarda un video, porque Meta escribió esa cadena pensando en imágenes y nunca la actualizó. El texto es inconsistente, la aplicación del límite no.

¿Las menciones @ en un caption son lo mismo que los usuarios etiquetados en la imagen?

Son dos mecanismos separados con dos topes separados. Las menciones @ viven dentro del texto del caption y tienen un tope de 20, mientras que user_tags coloca nombres de usuario en coordenadas x e y sobre la imagen y no tiene un tope publicado. Collaborators es un tercer mecanismo, distinto, con un tope de 3.