Limitación de frecuencia con la API Graph

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.

Hay dos tipos principales de límites de frecuencia que puede detectar tu aplicación: limitación de frecuencia en el nivel de la aplicación y limitación de frecuencia 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. Tu aplicación recibirá el código de error 4 si alcanzas estos límites.

Panel de límites de frecuencia

En el panel de aplicaciones consulta los gráficos sobre la actividad de limitación de frecuencia de tu aplicación.

Límites

A cada aplicación se imponen 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. Haz clic en cualquier ejemplo para obtener más detalles de los tipos de utilización.

En total, tu aplicación puede realizar 200 llamadas por hora por cada usuario. Por ejemplo, si tu aplicación tiene 100 usuarios, significa que puede realizar 20.000 llamadas. No hay un límite por usuario, por lo que un usuario podría hacer 19.000 de esas llamadas y otro podría hacer 1.000. Este límite se calcula con base en el número de llamadas realizadas en la hora anterior.

Cuando se limita la frecuencia de tu aplicación, todas las llamadas de la aplicación se limitarán, no solo las de un usuario específico.

El cálculo del número de usuarios para tu aplicación es la suma del número promedio de usuarios activos diarios más los nuevos inicios de sesión del día en curso como un valor estimado. La limitación de frecuencia de las aplicaciones con un número mayor de usuarios puede ser más precisa que la de aquellas con un número menor. Las aplicaciones con un número muy bajo de usuarios 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. Es difícil alcanzar estos límites, por lo que es un caso extremadamente inusual. Encontrarás esta información en el panel de detalles de cada ejemplo. 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 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 al respecto.

Recomendaciones

La limitación de frecuencia establece el máximo de llamadas a la API que se pueden realizar durante un período específico. Cuando se excede un límite de frecuencia, las llamadas a la API de una aplicación se limitan y devuelven errores por un breve tiempo. Cuando se limita una aplicación, en las llamadas siguientes se devolverá un error al emisor de la llamada con error code = 4, CodedException. Puede pasar hasta una hora antes de que tus solicitudes 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 tu aplicación está realizando suficientes llamadas como para que nuestro sistema considere imponerle una limitación de frecuencia, devolvemos un encabezado HTTP X-App-Usage. Este encabezado contiene el porcentaje que tu aplicación utiliza actualmente. Este porcentaje es igual al uso mostrado 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 frecuencia 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 frecuencia. 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 podría recibir 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?

Tu aplicación está superando 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 saber?

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