Qué devuelve el endpoint content_publishing_limit de Instagram

¿Qué devuelve el endpoint content_publishing_limit?

El endpoint content_publishing_limit de Meta devuelve un recuento de cuántos contenedores ha publicado ya una cuenta profesional de Instagram dentro de una ventana móvil de 24 horas, junto al techo contra el que se mide ese recuento. Es un endpoint de solo lectura. La referencia lo dice dos veces: "Creating: This operation is not supported" y la misma línea para actualizar y eliminar.

La forma de la petición, copiada de la referencia de Meta:

GET https://graph.facebook.com/<API_VERSION>/<IG_USER_ID>/content_publishing_limit
  ?fields=<LIST_OF_FIELDS>
  &since=<UNIX_TIMESTAMP>
  &access_token=<ACCESS_TOKEN>

Las apps construidas sobre Instagram API with Instagram Login envían la misma llamada a graph.instagram.com. La respuesta es un array data con un objeto dentro:

{
  "data": [
    {
      "quota_usage": 2,
      "config": {
        "quota_total": 50,
        "quota_duration": 86400
      }
    }
  ]
}

¿Qué significan quota_usage, quota_total y quota_duration?

Tres nombres de campo cargan con toda la respuesta, y Meta define cada uno en una frase.

quota_usage es el campo que te llega gratis. La nota de Meta sobre el parámetro fields dice: "A comma-separated list of fields you want returned. If omitted, the quota_usage field will be returned by default". Pide config de forma explícita o no verás el techo, solo el recuento.

El parámetro since estrecha la ventana. Meta lo describe como "A Unix timestamp no older than 24 hours", y añade que "If the since parameter is omitted, this value will be the number of times the app user has published a container within the last 24 hours". No puedes mirar más atrás de un día, que es lo mismo que decir que el endpoint no tiene memoria más allá de la cuota que aplica.

Una rareza vive en el propio ejemplo de petición de Meta. Consulta fields=quota_usage,rate_limit_settings, y rate_limit_settings no aparece en la tabla de campos de esa página ni en ningún otro sitio de la referencia de Instagram Platform. El ejemplo pide un campo que la documentación nunca define.

¿El tope son 50 publicaciones o 100?

Meta publica ambas cifras en páginas vivas, y nunca las reconcilia. La guía de publicación de contenido afirma: "Instagram accounts are limited to 100 API-published posts within a 24-hour moving period". La referencia de content_publishing_limit afirma que quota_total es "currently 50". La sección de carruseles de esa misma guía afirma: "Accounts are limited to 50 published posts within a 24-hour period".

Así que la guía se contradice internamente, y la referencia se pone del lado de la cifra más baja. No es una página caduca que Meta olvidó, es la documentación del endpoint del campo exacto que reporta el techo. La distancia entre la frase de 100 publicaciones y la de 50 es lo bastante antigua como para haber sobrevivido a varias versiones de la Graph API.

La solución práctica es dejar de leer cualquiera de las dos cifras y leer quota_total de la respuesta. Ese es el número contra el que se mide de verdad la cuenta, llega por cuenta y cuesta una petición conseguirlo.

¿Qué cuenta contra la cuota y qué no?

Publicar cuenta. Crear no. La distinción es exacta en la redacción de Meta, porque quota_usage cuenta "the number of times the app user has published an IG Container", y la guía nombra el endpoint donde se aplica: "This limit is enforced on the POST /<IG_ID>/media_publish endpoint when attempting to publish a media container".

La creación de contenedores tiene su propio techo, que casi ningún equipo alcanza. La referencia del endpoint de contenido afirma: "An Instagram account can only create 400 containers within a rolling 24 hour period". Ocho contenedores por publicación es una proporción generosa, así que un flujo que reintenta la creación de contenedores con agresividad puede agotar ese presupuesto mientras quota_usage sigue marcando cero, y el fallo no se parecerá en nada a un límite de tasa de publicación.

Los carruseles son el caso que conviene interiorizar si agrupas conjuntos de imágenes. Diez imágenes se convierten en una unidad de cuota, lo que hace programar publicaciones de carrusel en Instagram y Facebook mucho más barato contra el tope que diez publicaciones sueltas con las mismas imágenes.

¿Cómo deberías leer la respuesta antes de publicar?

Llama a content_publishing_limit antes de publicar, no después del fallo, y compara quota_usage con config.quota_total en lugar de con un número que fijaste en el código. Meta lo pide directamente: "We recommend that your app also enforce the publishing rate limit, especially if your app allows app users to schedule posts to be published in the future".

Tres detalles deciden si esa comprobación vale de algo:

• Pide config de forma explícita. Sin él obtienes un recuento de uso y nada con lo que compararlo.
• Trata la ventana como móvil, no como diaria. quota_duration son 86400 segundos medidos hacia atrás desde ahora, así que la capacidad vuelve poco a poco a lo largo del día en vez de a una hora de reinicio.
• Vuelve a leer antes de cada publicación de un lote, no una vez por lote. Una cola de 20 publicaciones que comprobó la cuota una sola vez al principio es una cola que puede pasarse del techo en la publicación 14.

Las herramientas de programación son donde más muerde esto, porque una cola se compromete a horas de publicación con horas o días de antelación mientras la cuota se gasta en el presente. Es la misma clase de problema que cualquier API de programación social construida sobre una cuota de plataforma: el calendario se escribe contra una capacidad que todavía no se ha medido.

¿Qué error devuelve Instagram cuando llegas al tope?

La referencia de códigos de error de Meta lo enumera con precisión. Una cuenta que ha agotado su cuota de publicación recibe un HTTP 400, código 9, subcódigo 2207042, con el mensaje de usuario: "You reached maximum number of posts that is allowed to be published by Content Publishing API".

La solución recomendada dice: "The app user has reached their daily publishing limit. Advise the app's user to try again the following day". Fíjate en el desajuste. La ventana está documentada como un periodo móvil de 24 horas en todas partes, y el consejo de aquí dice "the following day", que es lenguaje de calendario para una ventana móvil. La capacidad se libera 24 horas después de cada publicación individual, no a medianoche.

Los fallos vecinos tienen otro aspecto y se deberían manejar por separado. El código 4, subcódigo 2207051 devuelve "We restrict certain activity to protect our community. Tell us if you think we made a mistake", que Meta atribuye a una publicación "suspected to be spam". Eso no es un problema de cuota, y reintentar mañana no lo despejará. Otras plataformas trazan la misma línea entre una cuota que puedes esperar y una restricción que no, y por eso los límites de tasa publicados de Pinterest y los de Instagram necesitan rutas de manejo separadas en la misma cola.

¿Qué permisos necesita la llamada?

Los alcances del token cambian según el flujo de inicio de sesión, y Meta enumera ambos. Instagram API with Instagram Login necesita instagram_business_basic e instagram_business_content_publish. Instagram API with Facebook Login necesita instagram_basic, instagram_content_publish y pages_read_engagement, más ads_management o ads_read cuando "the app user was granted a role via the Business Manager on the Page connected to the targeted IG User".

Esos son los mismos alcances que exige la propia llamada de publicación, así que un token que puede publicar también puede leer la cuota. No hay un alcance de solo lectura más barato para comprobar la capacidad, lo que significa que la comprobación de cuota está disponible para cualquier app que la llegue a necesitar.

Preguntas frecuentes

¿Cuál es la ruta completa del endpoint?

GET /<IG_USER_ID>/content_publishing_limit, en graph.facebook.com para Instagram API with Facebook Login y en graph.instagram.com para Instagram API with Instagram Login.

¿El endpoint devuelve el límite por defecto?

No. Solo quota_usage vuelve por defecto. La referencia de Meta dice que el objeto config, que contiene quota_total y quota_duration, hay que pedirlo mediante el parámetro fields.

¿Hasta dónde puede llegar hacia atrás el parámetro since?

24 horas. Meta describe el valor como "A Unix timestamp no older than 24 hours", así que el endpoint no puede reportar uso de ninguna ventana anterior.

¿Los intentos de publicación fallidos cuentan contra quota_usage?

Meta no lo dice. El campo cuenta las veces que el usuario "has published an IG Container", que se lee como publicaciones correctas, pero la documentación nunca aborda una publicación que da error después de haber sido aceptada.

¿Crear un contenedor de contenido consume cuota?

No. La creación de contenedores se rige por una regla aparte, que una cuenta "can only create 400 containers within a rolling 24 hour period", y los contenedores caducan a las 24 horas se publiquen o no.

¿Por qué quota_total dice 50 cuando la guía dice 100?

Meta publica ambas cifras y nunca las resuelve. La referencia del endpoint dice que quota_total es "currently 50", la guía de publicación de contenido dice 100 en su sección de límites de tasa y 50 otra vez en su sección de carruseles. Lee el valor de la respuesta en vez de fiarte de cualquiera de las dos páginas.

¿Con qué frecuencia deberías volver a revisar la cuota en una cola de publicación?

Vuelve a comprobarla antes de cada publicación de la cola, no solo una vez al principio. La ventana es móvil, así que un lote de 20 publicaciones que solo comprobó la capacidad al inicio puede rebasar el tope hacia la publicación 14. Comparar quota_usage con config.quota_total en cada envío detecta ese desvío antes de que lo haga Instagram.

¿Un carrusel cuenta como una publicación o como varias contra quota_usage?

Un carrusel cuenta como una sola publicación sin importar cuántas imágenes contenga, según la frase de Meta "Carousels count as a single post". Diez imágenes publicadas juntas gastan la misma unidad de quota_usage que una sola imagen publicada sola. Eso hace que los carruseles salgan mucho más baratos contra el tope que publicar esas mismas imágenes por separado.

¿Qué pasa si una app ignora el límite de publicación?

Meta recomienda que las apps impongan el límite de frecuencia por su cuenta, sobre todo cuando permiten programar publicaciones con antelación, porque saltarse la comprobación solo retrasa el fallo hasta el momento de publicar. Una cuenta que supera la cuota recibe HTTP 400, código 9, subcódigo 2207042, y la capacidad vuelve 24 horas después de cada publicación, no en un reinicio diario. Una herramienta de programación que se salta esa comprobación previa se entera después de haberse comprometido ya con un horario de publicación que ya no puede cumplir.

¿Una restricción por spam es lo mismo que llegar al tope de publicación?

Una restricción por spam es un fallo distinto de un límite de cuota. El código 4, subcódigo 2207051, aparece cuando una publicación se "suspected to be spam", y reintentarlo al día siguiente no resuelve el problema como sí lo hace esperar la cuota. Esa diferencia importa en una cola, porque los dos errores necesitan rutas de manejo distintas, una que espera y otra que se detiene y marca el contenido.