Limitación de frecuencia con la API Graph

La limitación de frecuencia establece el máximo de llamadas a la API que se pueden realizar durante un período específico, y todas las aplicaciones tienen una.

Es posible que se desactiven aquellas que superen de forma excesiva o constante estas limitaciones.

Solo en circunstancias excepcionales se limita la frecuencia de la API Graph de Facebook. En este documento se describen esos límites y cómo manejarlos.

Tu aplicación puede recibir principalmente dos tipos de límites de frecuencia: en el nivel de la aplicación y en el nivel de la página.

Limitación de frecuencia en el nivel de la aplicación

Estos límites se aplican a las llamadas que se realizan mediante cualquier token de acceso que no sea un token de acceso de la página.

Todas las llamadas a la API que se realicen desde una aplicación una vez superado el límite de frecuencia se limitarán y devolverán el error error code = 4, CodedException. Cuando el porcentaje de uso durante las últimas horas se sitúe por debajo del límite, se podrán volver a realizar llamadas. Estos límites se calculan continuamente en intervalos de una hora y los porcentajes de uso actuales pueden consultarse en el panel de aplicaciones.

Panel de límites de frecuencia

La herramienta de limitación de frecuencia te da información sobre qué tan próxima está tu aplicación a que se le aplique una limitación. En el panel de aplicaciones, puedes consultar información sobre los límites de frecuencia que afectan a las aplicaciones a través de dos gráficos.

  • En el primero se muestra el porcentaje de uso actual que afecta a las respuestas de la API Graph devueltas. Se trata de una representación visual del valor de encabezado devuelto tras realizar solicitudes a la API Graph.
Gráfico de una aplicación que se aproxima a su límite de frecuencia
  • En el segundo figuran antiguos límites de frecuencia. Tienes la opción de visualizar los datos de las últimas 24 horas o los últimos 7 días. Puedes hacer clic en cualquier ejemplo del gráfico para ver más detalles sobre el uso, incluido un desglose por método. No todas las aplicaciones tienen un historial de datos, puesto que depende del volumen de llamadas. Es más probable que aquellas con un gran volumen de llamadas tengan un historial de datos disponible.
Gráfico de datos anteriores de una aplicación que superó los límites de frecuencia durante las últimas 24 horas.

Límites

El número de llamadas que tu aplicación puede realizar por hora es 200 veces el número de usuarios. No se trata de un límite por usuario, ya que cualquier usuario puede realizar más de 200 llamadas por hora, siempre que el total de llamadas de todos los usuarios no supere el máximo de la aplicación. Por ejemplo, si tu aplicación cuenta con 100 usuarios, esta puede realizar 20 000 llamadas por hora, aunque tus diez usuarios más activos podrían realizar 19 000 de ellas.

Si se aplica un límite de frecuencia a tu aplicación, se limitarán todas sus llamadas, no solo las de un usuario en concreto.

El número de usuarios de tu aplicación se calcula a partir de los usuarios activos por día y los nuevos inicios de sesión registrados en el día en curso. En períodos de poco uso diario, este número se calcula a partir de los usuarios activos por semana e, incluso, de los activos por mes. Las aplicaciones que consigan elevados niveles de interacción diaria tendrán límites de frecuencia más altos que aquellas con poca interacción, independientemente del número real de instalaciones de la aplicación.

Advertencias:

  • No todas las llamadas a la API están sujetas a límites de frecuencia, por lo que es posible que el número de llamadas que realices no coincida con lo que aparece en la herramienta de limitación de frecuencia.
  • También restringiremos las llamadas en función del tiempo de CPU empleado y el tiempo total. A pesar de no superar el límite de volumen de llamadas, los extremos que requieren muchos procesos pueden provocar que la aplicación llegue a los límites mencionados. Normalmente, las aplicaciones no suelen alcanzar el tiempo de CPU y los límites de tiempo totales, excepto en el caso de los extremos especializados. Si está disponible, podrás consultar información sobre los extremos que emplean mucho tiempo de CPU o tiempo total en el gráfico de datos anteriores.
  • La API de estadísticas de anuncios y la API de marketing pueden usar un conjunto diferente de límites de velocidad. Consulta el documento "Limitación de velocidad de la API de marketing" en https://developers.facebook.com/docs/marketing-api/api-rate-limiting para obtener más información al respecto.

Recomendaciones

Para evitar la limitación de frecuencia, puedes:

  • Distribuir las consultas de manera uniforme entre dos intervalos de tiempo para evitar generar picos de tráfico.
  • Usar filtros para limitar el tamaño de la respuesta de datos y evitar llamadas que soliciten datos superpuestos.
  • Usar el encabezado de limitación de frecuencia para equilibrar dinámicamente el volumen de la llamada.

Encabezado de la limitación de frecuencia

Todas las respuestas a las llamadas realizadas a la API Graph incluyen un encabezado HTTP X-App-Usage. Este encabezado contiene el porcentaje que tu aplicación utiliza actualmente. Este porcentaje es igual al uso que aparece en el gráfico de limitación de frecuencia. Usa este número para equilibrar dinámicamente tu carga de llamadas y evitar que reciba una limitación.

El encabezado de limitación de frecuencia es una cadena con formato JSON que tiene el siguiente aspecto:

{
  "call_count"    : x, 
  "total_time"    : y, 
  "total_cputime" : z
}

Los valores para "x", "y" y "z" son números enteros que representan el porcentaje de valores utilizados para cada uno de los resultados. Cuando cualquiera de estos resultados supera 100, la frecuencia de la aplicación se limita.

Limitación de frecuencia en el nivel de la página

Estos límites se aplican a las llamadas que se realizan mediante un token de acceso de la página. Tu aplicación recibirá el código de error 32 si alcanzas estos límites.

La entrada de blog en https://developers.facebook.com/blog/post/2016/06/16/page-level-rate-limits/ proporciona una explicación detallada de la limitación de velocidad en el nivel de la página.

Panel de límites de frecuencia

Para cada página cuyo token de acceso utilice la aplicación para realizar llamadas, puedes ver los gráficos de limitación de frecuencia en esa página.

Límites

Los límites de frecuencia se imponen en cada página en vez de en la aplicación. La herramienta de limitación de frecuencia te proporcionará información sobre cuántas aplicaciones usan el token de acceso de esa página y sobre qué tan próxima está la página a que se le aplique una limitación. Haz clic en cualquier ejemplo para obtener más detalles de los tipos de utilización.

El número de personas que interactúan diariamente y usan una página es el número de personas únicas que interactuaron con la página en un período de 24 horas. Una interacción con una página consiste en un clic en la página o en su contenido.

El número de usuarios que interactuaron en las 24 horas anteriores se usa para calcular los límites de frecuencia para el período actual de 24 horas.

Se pueden hacer, en nombre de la página, 4.800 llamadas por usuarios que interactúan al día en un total de 24 horas. Por ejemplo, si la página tiene 100 usuarios que interactúan cada día, se pueden realizar 480.000 llamadas en nombre de la página en un período de 24 horas. Este período de 24 horas es un intervalo que se desplaza y se actualiza cada pocos minutos. El límite de llamadas es un límite por página, por lo que una aplicación podría hacer 400.000 llamadas y otra podría hacer 80.000. Si una página tiene limitación de frecuencia, solo se limitarán las llamadas de la aplicación que usan el token de acceso de esa página. Esto significa que tu aplicación aún puede funcionar normalmente para otras llamadas.

El número de llamadas a la página se calcula como el número estimado de llamadas que usan el token de acceso de la página al día. La limitación de frecuencia de las páginas con un número mayor de llamadas al día puede ser más precisa que la de aquellas con un número menor. Las páginas con un número muy bajo de llamadas al día pueden tener problemas con el límite de frecuencia.

Advertencias:

  • No todas las llamadas a la API están sujetas a límites de frecuencia, por lo que es posible que el número de llamadas que realices no coincida con lo que ves en la herramienta de limitación de frecuencia.
  • Facebook también limita las llamadas con base en el tiempo de CPU utilizado y el tiempo total. Haz clic en la herramienta de limitación de frecuencia de tu panel para ver más detalles.
  • La API de estadísticas de anuncios y la API de marketing pueden usar un conjunto diferente de límites de velocidad. Consulta el documento Limitación de velocidad de la API de marketing para obtener más información al respecto.

Recomendaciones

Cuando se limita una página, en las llamadas siguientes se devolverá un error al emisor de la llamada con error code = 32, CodedException. Puede pasar hasta una hora antes de que tus solicitudes para esa página se vuelvan a aceptar.

Para evitar la limitación de frecuencia, puedes:

  • Distribuir las consultas de manera uniforme entre dos intervalos de tiempo para evitar generar picos de tráfico.
  • Usar filtros para limitar el tamaño de la respuesta de datos y evitar llamadas que soliciten datos superpuestos.
  • Usar el encabezado de limitación de frecuencia para equilibrar dinámicamente el volumen de la llamada.

Encabezado de la limitación de frecuencia

Si se realizan suficientes llamadas en nombre de una página como para que nuestro sistema considere imponerle una limitación de frecuencia, devolvemos un encabezado HTTP X-Page-Usage. Este encabezado contiene el porcentaje que la página utiliza actualmente. Si realizas llamadas mediante el token de acceso de una página, obtendrás el valor X-Page-Usage para esa página únicamente. Este porcentaje es igual al uso mostrado en el gráfico de limitación de frecuencia de esa página. Usa este número para equilibrar dinámicamente tu carga de llamadas y evitar que reciba una limitación.

El encabezado de limitación de frecuencia es una cadena con formato JSON que tiene el siguiente aspecto:

{
  "call_count"    : x, 
  "total_time"    : y, 
  "total_cputime" : z
}

Los valores para "x", "y" y "z" son números enteros que representan el porcentaje de valores utilizados para cada uno de los resultados. Cuando cualquiera de estos resultados supera 100, la frecuencia de la aplicación se limita.

Limitación de frecuencia en la cuenta

Estos límites se aplican a las llamadas que se realizan mediante tokens de acceso de usuario. Tu aplicación recibirá el código de error 17 si se alcanza este límite. Esto sucede si una cuenta de usuario específica está haciendo demasiadas llamadas a la API.

Nota:

Se incluyen las llamadas de usuario realizadas desde varias aplicaciones y no solo desde la tuya.

Si se limita la frecuencia de un usuario, se regulan sus llamadas a la API.

Para evitar la limitación de frecuencia, puedes:

No hay nada que puedas hacer para evitarlo. El usuario está haciendo demasiadas llamadas (posiblemente a través de otras aplicaciones) y, por lo tanto, se limita su frecuencia. Sin embargo, si esto sucede para demasiados usuarios de una aplicación, lo más probable es que sean las llamadas a la API de esa misma aplicación las que están ocasionando la situación. En ese caso, debes reducir sus llamadas o distribuirlas de manera más uniforme.

PREGUNTAS FRECUENTES

¿Qué consideramos una llamada a la API?

Todas las llamadas cuentan para los límites de frecuencia, no solo las solicitudes de API HTTPS individuales. Por ejemplo, puedes hacer una sola llamada a la API y especificar varios identificadores, pero cada identificador contaría como su propia llamada a la API, aunque solo estás haciendo una solicitud de API HTTPS.

Para ilustrar este concepto, ve los siguientes ejemplos:

Solicitudes de ejemplo Cantidad de llamadas a la API

GET https://graph.facebook.com/photos?id=4
GET https://graph.facebook.com/photos?id=5
GET https://graph.facebook.com/photos?id=6

3

GET https://graph.facebook.com/photos?id=4,5,6

3

En un escenario donde necesitas cruzar varios objetos por identificador, te recomendamos que utilices el segundo enfoque, ya que mejorará el rendimiento de tus respuestas de API, aunque no mejorará la cantidad de llamadas realizadas para los fines de limitación de frecuencia.

También puedes utilizar la API por lotes para procesar por lotes tus solicitudes, pero ten en cuenta que cada solicitud secundaria es su propia llamada a la API o, incluso, varias llamadas a la API en caso de especificar muchos identificadores.

Si tu aplicación o página se vuelve de frecuencia limitada, las llamadas a la API que detecten errores de limitación de frecuencia también cuentan para el límite de frecuencia.


¿Qué errores verá mi aplicación?
Tipo de limitación Al menos Código de error

Limitación en el nivel de la aplicación

200 llamadas/persona/hora

4

Limitación en el nivel de la cuenta

No se aplica

17

Limitación en el nivel de la página

4.800 llamadas/persona/24 horas

32

Limitación en un nivel personalizado

No se aplica

613


Me aparece el código de error 613, ¿qué hago?

Si la respuesta del error contiene "error_subcode 1996" quiere decir que Facebook detectó un comportamiento incoherente en el volumen de solicitudes de tu aplicación a la API. Es posible que aparezca este error si hiciste cambios recientemente que afecten al número de solicitudes a la API.

Si no ves el subcódigo, significa que tu aplicación supera un límite de frecuencia personalizado. Ponte en contacto con tu ejecutivo de cuenta, quien te ayudará a solucionar este problema.


Estoy creando una herramienta de extracción. ¿Hay algo más que deba tener en cuenta?

Si estás creando un servicio que extrae datos, lee nuestras condiciones de extracción.