El límite de tasa de la API de Instagram es 4800 por impresión

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

Una sola fórmula define el límite de tasa de la API de Instagram, y Meta la imprime como una línea única tanto en la referencia de rate limiting de Graph API como en la visión general de Instagram Platform: Calls within 24 hours = 4800 * Number of Impressions.

La frase que la rodea importa tanto como la fórmula. Meta escribe: "Calls to the Instagram Platform endpoints, excluding messaging, are counted against the calling app's call count. An app's call count is unique for each app and app user pair, and is the number of calls the app has made in a rolling 24 hour window."

En esa frase se esconden tres restricciones. El recuento pertenece a la app, no a la cuenta. Está acotado a un par de app y usuario de app a la vez, así que un cliente ajetreado no puede dejar sin recursos a uno tranquilo. Y la ventana se desliza, así que nada se reinicia a medianoche. Las llamadas caducan una a una, 24 horas después de haberse hecho.

Instagram Platform vive dentro de la categoría Business Use Case de Meta y no de la antigua categoría Platform Rate Limits. Las peticiones de Marketing API y de Instagram están sujetas a los límites Business Use Case; las peticiones planas de Graph API están sujetas a los límites Platform. Cuando podrían aplicarse ambos, Meta lo resuelve en una línea: "If both Platform and Business Use Case rate limits can be applied to a request, BUC rate limits will be applied."

¿Sobre qué se aplica el multiplicador 4800?

Sobre las impresiones, y Meta define la palabra de forma estrecha: "The Number of Impressions is the number of times any content from the app user's Instagram professional account has entered a person's screen within the last 24 hours."

Léelo como un recuento de pantallas, no de seguidores, no de publicaciones y no de alcance. Cuenta apariciones, así que una persona que pasa scrolleando por cuatro de tus publicaciones aporta cuatro. Cubre "any content" de la cuenta, así que publicaciones viejas que siguen trayendo tráfico cuentan igual que la de esta mañana. Y se mide en las mismas 24 horas móviles que las llamadas que financia, lo que hace que la asignación se mueva de forma continua en lugar de a saltos.

Eso produce un presupuesto que escala con la atención. Una cuenta cuyas publicaciones entraron en pantallas 50.000 veces en el último día financia 240.000.000 de llamadas, una cifra a la que ningún flujo de publicación se acerca. La fórmula solo muerde por abajo, porque Meta no publica ningún suelo: 4800 multiplicado por cero impresiones son cero llamadas, y en ningún punto de la referencia de rate limiting Meta enuncia una asignación mínima para una cuenta que nadie ha visto.

La misma estructura aparece en otros puntos de la tabla de Meta. Las llamadas a Pages API hechas con un token de Página o de usuario de sistema usan Calls within 24 hours = 4800 * Number of Engaged Users, y LeadGen usa Calls within 24 hours = 4800 * Leads Generated. El multiplicador 4800 es la cifra de la casa de Meta para un caso de uso de negocio de 24 horas; lo único que cambia es lo que se multiplica.

¿Cómo se lee la cabecera X-Business-Use-Case-Usage?

Meta devuelve el uso en una cabecera de respuesta en lugar de en el cuerpo: "All API responses made by your app that are rate limited using the BUC logic include an X-Business-Use-Case-Usage HTTP header with a JSON-formatted string that describes current application rate limit usage. This header can return up to 32 objects in one call."

El valor de la cabecera es un objeto JSON indexado por ID de negocio, y cada entrada lleva estos campos.

Campo	Lo que Meta dice que contiene
business-id	El ID del negocio asociado al token que hace las llamadas a la API
call_count	Un número entero que expresa el porcentaje de llamadas permitidas que ha hecho tu app
total_cputime	Un número entero que expresa el porcentaje de tiempo de CPU asignado al procesamiento de consultas
total_time	Un número entero que expresa el porcentaje de tiempo total asignado al procesamiento de consultas
estimated_time_to_regain_access	Tiempo, en minutos, hasta que las llamadas dejen de estar estranguladas
type	Tipo de límite aplicado, uno de ads_insights, ads_management, custom_audience, instagram, leadgen, messenger o pages

Para el trabajo con Instagram el campo con el que hay que comparar es type, y el valor a buscar es instagram. Una app que también toca Pages o Ads recibe varios objetos en la misma cabecera, y leer el equivocado te informa del presupuesto equivocado.

Cada uno de los tres números de uso es un porcentaje, no un recuento. call_count en 62 significa que se ha gastado el 62 por ciento de la asignación, y Meta nunca te dice el denominador, porque el denominador es esa cifra de impresiones recalculada de forma continua. Ningún endpoint devuelve tu techo de llamadas actual como número entero.

La cabecera tampoco aparece en todas las respuestas. La redacción de Meta es que las estadísticas de uso en tiempo real vienen "included with most API responses once enough calls have been made to an endpoint." Trata una cabecera ausente como falta de información, no como uso cero.

¿Por qué la cabecera dice una hora si la fórmula dice 24 horas?

Porque las dos páginas de Meta se contradicen, y la contradicción está viva en el mismo documento. La sección de Instagram habla de una "rolling 24 hour window." La tabla de la cabecera, unas pantallas más abajo, define call_count como "A whole number expressing the percentage of allowed calls made by your app over a rolling one hour period."

Las dos frases describen el mismo campo de la misma cabecera para la misma API. Una de ellas es falsa para Instagram. La redacción de una hora coincide con la sección Platform Rate Limits de más arriba en la página, donde las llamadas a nivel de app sí se miden por hora, que es el origen más probable del desajuste.

Nada en la documentación lo resuelve, así que planifica para la ventana larga. Si asumes que el contador se limpia en una hora y en realidad se limpia en 24, reintentas contra un muro. Si asumes 24 y se limpia en una, esperaste más de lo necesario. Solo uno de esos dos errores rompe un calendario de publicación.

Un segundo hueco publicado vive en las tablas de errores. La lista de errores de Business Use Case de Meta nombra el error code 80002 para el tipo Instagram, sin subcódigo. La referencia de códigos de error de Instagram Platform, la página que de verdad leerías mientras depuras una publicación, no lista 80002 por ninguna parte. Mapéalo tú.

¿Qué pasa cuando call_count llega a 100?

Las peticiones fallan con un código de error dedicado. Meta escribe: "When your app reaches its Business Use Case rate limit, subsequent requests made by your app will fail and the API will respond with an error code." Para el tipo Instagram ese código es 80002.

El tiempo de CPU y el de reloj se estrangulan por separado del volumen de llamadas. Meta repite las mismas dos líneas bajo cada caso de uso de negocio: "When total_cputime reaches 100, calls may be throttled" y "When total_time reaches 100, calls may be throttled." Basta con que cualquiera de los tres llegue a 100. Un puñado de consultas pesadas puede agotar total_cputime mientras call_count sigue en un solo dígito.

Una vez estrangulado, estimated_time_to_regain_access lleva la espera en minutos, y la instrucción que sigue es la importante: "When the limit has been reached, stop making API calls. Continuing to make calls will continue to increase your call count, which will increase the time before calls will be successful again."

Reintentar alarga el bloqueo. Eso es lo bastante inusual como para merecer un diseño propio, porque un backoff exponencial por defecto sigue enviando peticiones, y cada una de ellas extiende la penalización. El comportamiento correcto ante un 80002 es aparcar la cola hasta que la cabecera diga otra cosa. La misma disciplina rinde con la cuota diaria de publicación, que es un techo aparte con su propio error.

El resto de los consejos de Meta van de espaciar más que de volumen: "Spread out queries evenly to avoid traffic spikes" y "Use filters to limit the data response size and avoid calls that request overlapping data." Hay además una regla de conteo que pilla a quien agrupa IDs. Meta enuncia que "each ID counts as one API call", y lo demuestra: tres peticiones separadas de un solo ID cuentan como tres llamadas, y una petición con ids=4,5,6 también cuenta como tres.

Dos respuestas al error 80002

Detener la cola

• call_count deja de subir
• estimated_time_to_regain_access cuenta hacia atrás
• las llamadas vuelven a funcionar cuando termina la espera

Seguir reintentando

• cada reintento aumenta más el call_count
• estimated_time_to_regain_access crece
• la espera antes de que las llamadas vuelvan a funcionar se alarga

¿Qué endpoints de Instagram quedan fuera de este límite?

Dos familias, y Meta las nombra de forma explícita.

Superficie	Límite que se aplica
Publicación, medios, insights, comentarios	4800 * Number of Impressions por 24 horas
Business Discovery, Hashtag Search	Platform Rate Limits, no Business Use Case
Conversations API	2 llamadas por segundo y cuenta profesional
Send API, texto y enlaces	100 llamadas por segundo y cuenta profesional
Send API, audio o vídeo	10 llamadas por segundo y cuenta profesional
Private Replies, comentarios en directo	100 llamadas por segundo y cuenta profesional
Private Replies, publicaciones y reels	750 llamadas por hora y cuenta profesional

La mensajería queda fuera de la fórmula de impresiones por completo y funciona con techos por segundo y por hora. Business Discovery y Hashtag Search caen de vuelta en Platform Rate Limits, donde la fórmula a nivel de app es Calls within one hour = 200 * Number of Users.

El límite de tasa tampoco es la cuota de publicación. Son sistemas separados con errores separados, y confundirlos malgasta tiempo de depuración: una publicación bloqueada por volumen devuelve 80002, mientras que una publicación bloqueada por la cuota de publicación de contenido devuelve el código 9, subcódigo 2207042. Otras redes se dividen igual, ya sean los techos de peticiones que Bluesky publica por endpoint o el presupuesto diario de unidades que YouTube mide y te deja solicitar ampliar.

Preguntas frecuentes

¿Cuál es la fórmula del límite de tasa de la API de Instagram?

Calls within 24 hours = 4800 * Number of Impressions. Meta la publica en la referencia de rate limiting de Graph API y la repite en la visión general de Instagram Platform.

¿Qué cuenta como impresión en el límite de tasa de Instagram?

Meta lo define como "the number of times any content from the app user's Instagram professional account has entered a person's screen within the last 24 hours." Cuenta apariciones de cualquier contenido, no seguidores y no publicaciones.

¿Qué código de error significa que se alcanzó el límite de tasa de la API de Instagram?

El código de error 80002. Meta lo lista frente al tipo de caso de uso de negocio de Instagram sin subcódigo, y no lo repite en la referencia de códigos de error de Instagram Platform.

¿Cómo se consulta el uso actual del límite de tasa de la API de Instagram?

Lee la cabecera de respuesta X-Business-Use-Case-Usage, busca el objeto donde type sea instagram y revisa call_count, total_cputime y total_time. Los tres son porcentajes de la asignación.

¿Reintentar tras un error de límite de tasa lo empeora?

Sí. Meta escribe que seguir haciendo llamadas "will continue to increase your call count, which will increase the time before calls will be successful again." Para la cola y lee estimated_time_to_regain_access.

¿Los endpoints de mensajería de Instagram entran en la fórmula de 4800?

No. Meta excluye la mensajería de la fórmula de impresiones y publica techos por segundo y por hora para las APIs de Conversations, Send y Private Replies.

¿Se reinicia el límite de tasa de la API de Instagram a una hora fija cada día?

El límite no se reinicia a una hora fija, ni a medianoche ni en otro momento. Meta cuenta las llamadas en una ventana móvil de 24 horas, de modo que cada llamada sale del conteo exactamente 24 horas después de haberse hecho. El margen disponible se mueve de forma continua en lugar de volver a cero según un horario.

¿La cuenta de llamadas de la API de Instagram se comparte entre todas las apps conectadas a mi cuenta?

Cada app mantiene su propio conteo. Meta asigna el contador de llamadas a un único par de app y usuario de la app, así que una app con mucho tráfico no puede agotar el margen que pertenece a otra app que accede a la misma cuenta.

¿En qué se diferencia el límite de tasa de la API de Instagram de la cuota diaria de publicación?

Son sistemas separados con errores separados. El límite de tasa descrito aquí bloquea con el código de error 80002 cuando call_count, total_cputime o total_time llegan a 100. La cuota diaria de publicación es un tope distinto y falla con el código 9, subcódigo 2207042, así que un bloqueo de un tipo nunca explica un bloqueo del otro.

¿Las llamadas a Business Discovery y Hashtag Search cuentan en la fórmula de 4800?

Quedan fuera de ella. Ambos endpoints funcionan bajo la categoría más antigua de Meta, Platform Rate Limits, en lugar de Business Use Case, donde la fórmula que rige es 200 veces el número de usuarios por hora en vez de 4800 veces las impresiones.