Limitación de frecuencia en la API Graph

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: del nivel de aplicación y a nivel de la 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. Si alcanzas estos límites, tu aplicación recibirá el código de error 4.

Panel de limitaciones de frecuencia

Puedes ver los gráficos de la actividad de limitación de frecuencia de tu aplicación en el panel de aplicaciones.

Limitaciones

Cada aplicación tiene una limitación 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. Haz clic en cualquier muestra para obtener mayor detalle sobre los tipos de uso.

Tu aplicación puede realizar un total de 200 llamadas por hora y usuario. Por ejemplo, si la aplicación dispone de 100 usuarios, puede realizar 20 000 llamadas. Esta limitación no se aplica por usuario, por lo que una persona podría realizar 19 000 llamadas y, otra, 1000. Se calcula en función del número de llamadas realizadas durante la hora anterior.

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 es una estimación que se calcula como la media de los usuarios activos diarios más los nuevos inicios de sesión registrados en el día en curso. Es posible que las aplicaciones con un mayor número de usuarios tengan una limitación de frecuencia más precisa que el resto. En cambio, las aplicaciones con un número muy reducido de usuarios 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. No es fácil alcanzar estos límites, por lo que no suele darse el caso. Esta información se facilita en el panel de detalles de cada muestra. 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 frecuencia. Consulta el documento Limitación de frecuencia 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

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. Cuando se supera una limitación de frecuencia, todas las llamadas a la API desde la aplicación quedan restringidas y fallan durante un breve período de tiempo. Una vez que se restringe una aplicación, la persona que realiza la llamada recibe un error por cada llamada posterior con error code = 4, CodedException. Pueden hacer falta hasta dos horas para que se vuelvan a aceptar solicitudes.

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 tu aplicación realiza suficientes llamadas como para que nuestro sistema considere limitar la frecuencia, devolvemos un encabezado HTTP X-App-Usage. Este encabezado 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 frecuencia 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 frecuencia. 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.

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?

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 un extractor. ¿Hay algo más de lo que deba preocuparme?

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