Limitación de frecuencia en la API Graph

La limitación de frecuencia define el número máximo de llamadas a la API que se pueden realizar dentro de un tiempo especificado y todas las aplicaciones tienen una.

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

La API Graph de Facebook limita la frecuencia solamente en circunstancias extraordinarias. En este documento se describen dichos límites y cómo gestionarlos.

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

Límites de frecuencia del nivel de aplicación

Estas limitaciones se aplican a las llamadas realizadas utilizando identificadores de acceso que no corresponden a páginas.

Todas las llamadas a la API que se realicen desde una aplicación una vez superada la limitación 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 limitaciones de frecuencia

La herramienta de limitación de frecuencia proporciona información sobre el margen que le queda a tu aplicación antes de sufrir una restricció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 limitación 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 ha superado 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 una limitación 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 descargas de la aplicación.

Advertencias:

  • No todas las llamadas a la API están sujetas a limitaciones 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 utilizar un conjunto distinto de limitaciones 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 sobre esta API.

Recomendaciones

Para evitar que se limite la frecuencia:

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

Encabezado de limitación de frecuencia

Todas las respuestas a las llamadas realizadas a la API Graph incluyen un encabezado HTTP X-App-Usage, el cual contiene el porcentaje actual de uso de tu aplicación. Este porcentaje es igual al uso que aparece en el gráfico de limitación de frecuencia. Utiliza esta cifra para equilibrar de forma dinámica el volumen de llamadas, con el fin de evitar posibles restricciones.

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

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

Los valores de “x”, “y” y “z” son números enteros que representan los valores de porcentaje de uso de cada uno de los indicadores. Si alguno de estos indicadores pasa de 100, se limitará la frecuencia de la aplicación.

Limitación de frecuencia a nivel de página

Estas limitaciones se aplican a las llamadas realizadas utilizando un identificador de acceso de la página. Si alcanzas estos límites, tu aplicación recibirá el código de error 32.

Encontrarás una descripción detallada de las limitaciones de velocidad a nivel de página en la publicación de blog https://developers.facebook.com/blog/post/2016/06/16/page-level-rate-limits/.

Panel de limitaciones de frecuencia

Puedes consultar gráficos de limitación de frecuencia de todas las páginas cuyos identificadores se utilicen en tu aplicación para realizar llamadas.

Limitaciones

Las limitaciones de frecuencia no se imponen a las aplicaciones, sino a las páginas. La herramienta de limitación de frecuencia ofrece información sobre el número de aplicaciones que utilizan el identificador de acceso de la página, así como sobre el margen que le queda a dicha página antes de sufrir una restricción. Haz clic en cualquier muestra para obtener mayor detalle sobre los tipos de uso.

El número de personas activas diarias que utilizan una página es el número único de personas que han interactuado con la página en un período de 24 horas. Una interacción con una página es un clic en la página o en su contenido.

El número de usuarios activos de las 24 horas anteriores se utiliza para calcular las limitaciones de frecuencia del intervalo de 24 horas en curso.

Se pueden realizar un total de 4800 llamadas por usuario activo diario en nombre de la página durante un período de 24 horas. Por ejemplo, si la página tiene 100 usuarios activos diarios, se pueden realizar 480 000 llamadas en nombre de la página en un período de 24 horas. Este período es un intervalo móvil que se actualiza cada pocos minutos. El límite de llamadas se aplica por página, por lo que una aplicación podría realizar 400 000 llamadas y, otra, 80 000. Si se aplica una limitación de frecuencia a una página, solo se limitarán las llamadas realizadas desde tu aplicación que utilicen el identificador de acceso de dicha página. Por lo tanto, tu aplicación seguirá funcionando con normalidad de producirse otras llamadas.

El número de llamadas a tu página se calcula como el número estimado de llamadas al día que se realizan usando tu identificador de acceso a la página. Es posible que las páginas con un mayor número de llamadas al día tengan una limitación de frecuencia más precisa que aquellas con un número más reducido. En cambio, las páginas con un número muy reducido de llamadas al día pueden tener problemas con esta limitación.

Advertencias:

  • No todas las llamadas a la API están sujetas a limitaciones 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.
  • Facebook también restringe las llamadas en función del tiempo de CPU empleado y el tiempo total. Para obtener más información, haz clic en la gráfica, en la herramienta de limitación de frecuencia del panel.
  • La API de estadísticas de anuncios y la API de marketing pueden utilizar un conjunto distinto de limitaciones de velocidad. Consulta el documento Limitación de velocidad de la API de marketing para obtener más información sobre esta API.

Recomendaciones

Una vez que se restringe una página, la persona que realiza la llamada recibe un error por cada llamada posterior con error code = 32, CodedException. Puede pasar hasta una hora antes de que se vuelvan a aceptar solicitudes a la página.

Para evitar que se limite la frecuencia:

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

Encabezado de limitación de frecuencia

Si se realizan suficientes llamadas en nombre de una página como para que nuestro sistema considere limitar la frecuencia, devolvemos un encabezado HTTP X-Page-Usage. Este encabezado contiene el porcentaje actual de uso de la página. Si realizas llamadas utilizando el identificador de acceso de una página, solamente obtendrás el valor de X-Page-Usage de dicha página. Este porcentaje es igual al uso que aparece en el gráfico de limitación de frecuencia correspondiente a dicha página. Utiliza esta cifra para equilibrar de forma dinámica el volumen de llamadas, con el fin de evitar posibles restricciones.

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

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

Los valores de “x”, “y” y “z” son números enteros que representan los valores de porcentaje de uso de cada uno de los indicadores. Si alguno de estos indicadores pasa de 100, se limitará la frecuencia de la aplicación.

Limitación de frecuencia a nivel de cuenta

Estas limitaciones se aplican a las llamadas realizadas utilizando identificadores de acceso de usuario. Si se alcanza este límite, tu aplicación recibirá el código de error 17, que se produce cuando una cuenta de usuario determinada realiza demasiadas llamadas a la API.

Nota:

Esto puede incluir las llamadas de usuario realizadas a través de muchas aplicaciones (no solo la tuya).

Cuando se aplica la limitación de frecuencia a un usuario, se restringen sus llamadas.

Para evitar que se limite la frecuencia:

No se puede hacer nada para evitarlo. El usuario está realizando demasiadas llamadas (es posible que a través de otras aplicaciones), por lo que se le aplica una limitación de frecuencia. Sin embargo, si esto sucede con muchos usuarios de una misma aplicación, es muy probable que la causa del exceso sean las llamadas a la API realizadas a través de dicha aplicación. En este caso, deberías reducir estas llamadas o repartirlas de forma más uniforme en el tiempo.

URL de la foto del perfil

Las URL de la foto del perfil que devuelve la API Graph pueden tener distintos límites de frecuencia. Cuando alcances dichos límites, la solicitud devolverá un código de respuesta HTTP 429 (demasiadas solicitudes). Si alcanzas el límite de frecuencia continuamente:

  • Distribuye las consultas de manera uniforme en varios intervalos de tiempo.
  • Carga la foto en el lado del cliente en lugar de en el lado del servidor.
  • Si es necesario que cargues la foto en el lado del servidor, almacénala en caché.

Preguntas frecuentes

¿Qué consideramos una llamada a la API?

En lo que respecta a la limitación de frecuencia, se tienen en cuenta todas las llamadas, no solo las solicitudes HTTPS a la API. Por ejemplo, puedes realizar una sola llamada a la API y especificar varios identificadores, pero cada identificador contaría como una llamada, aunque solo realices una solicitud HTTPS a la API.

Para ilustrar este concepto, consulta los siguientes ejemplos:

Solicitudes de ejemplo Número 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 en el que tengas que pasar varios objetos según el identificador, te recomendamos utilizar la segunda opción, ya que mejorará el rendimiento de las respuestas de la API (no así el número de llamadas realizadas a efectos de limitación de frecuencia).

También puedes utilizar la API de lotes para procesar tus solicitudes de forma agrupada, pero ten en cuenta que cada subsolicitud constituye una llamada a la API, o incluso varias en caso de que especifiques varios identificadores.

Si se aplica una limitación de frecuencia a tu aplicación o página, las llamadas a la API en las que se produzcan errores relacionados también se tendrán en cuenta de cara a esta limitación.


¿Qué errores verá mi aplicación?
Tipo de limitación Valor mínimo Código de error

Restricción del nivel de aplicación

200 llamadas por persona y hora

4

Restricción a nivel de cuenta

No es aplicable.

17

Restricción a nivel de página

4800 llamadas por persona cada 24 horas

32

Restricción personalizada

No es aplicable.

613


He recibido el código de error 613. ¿Qué puedo hacer?

Si la respuesta del error contiene “error_subcode 1996” quiere decir que Facebook ha detectado un comportamiento incoherente en el volumen de solicitudes de tu aplicación a la API. Es posible que aparezca este error si has realizado 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 administrador de socios para obtener ayuda con este problema.


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

Si creas un servicio que extrae datos, consulta nuestras condiciones de extracción.