Tres porcentajes y ningún reloj: así es la cabecera x-app-usage de Meta

¿Qué es la cabecera x-app-usage?

En las respuestas de la Graph API, la cabecera x-app-usage de Meta le dice a una app cuánto de su propio límite de tasa lleva gastado. La referencia de limitación de tasa la presenta en una frase: "Endpoints that receive enough requests from your app will include a X-App-Usage or X-Ad-Account-Usage (for v3.3 and older Ads API calls) HTTP header in their responses. The header will contain a JSON-formatted string that describes current application rate limit usage."

En esa frase se esconden dos condiciones. La cabecera pertenece a la app, no a la cuenta ni al usuario cuyo token hizo la llamada. Y llega solo en endpoints que han visto tráfico suficiente, algo que Meta reformula en otro sitio diciendo que las cabeceras van "included with most API responses once enough calls have been made to an endpoint." Una respuesta sin x-app-usage significa que Meta decidió no informar, no que el uso sea cero.

El valor es un objeto JSON con tres claves y nada más. El propio ejemplo de Meta:

x-app-usage: {
  "call_count": 28,         // Percentage of calls made
  "total_time": 25,         // Percentage of total time
  "total_cputime": 25       // Percentage of total CPU time
}

Qué solicitudes reciben esta cabecera y no otra depende de la API y del token. Meta lo separa con claridad: "Graph API requests are subject to Platform Rate Limits, while Marketing API and Instagram Platform requests are subject to Business Use Case (BUC) Rate Limits." Las llamadas a la Pages API caen en un lado o en otro según la credencial, con los tokens de acceso de aplicación y de usuario en el lado de Platform y los de usuario de sistema o de Página en el de business use case.

¿Qué significan los tres campos de x-app-usage?

Los tres son porcentajes de una cuota, no recuentos de nada.

La palabra "whole" está trabajando de verdad. Todos los valores de x-app-usage son enteros, así que la lectura más fina que obtienes es un uno por ciento del presupuesto. La otra cabecera de Meta a nivel de app es más precisa con la misma idea: el campo acc_id_util_pct de X-Ad-Account-Usage aparece en el ejemplo como 9.67, con decimales. x-app-usage redondea.

Los tres campos también limitan de forma independiente. Meta adjunta las mismas dos líneas a los dos campos de tiempo: "When total_cputime reaches 100, calls may be throttled" y "When total_time reaches 100, calls may be throttled." Un puñado de consultas caras puede llevar total_cputime hacia el techo mientras call_count sigue en un solo dígito, así que una app que solo vigila el volumen de llamadas se pierde dos de las tres formas en que la bloquean.

Fíjate en lo que Meta no publica ahí. La referencia enuncia un umbral para total_cputime y un umbral para total_time, y nunca escribe la frase equivalente para call_count en la sección de cabeceras de Platform. Lo que dice en su lugar es general: "Once a rate limit is reached, any subsequent requests made by your app will fail and the API will return an error code until enough time has passed for the call count to drop below the limit." Lee el 100 de call_count como el límite de todos modos, porque nada en el documento sugiere otro número.

¿Contra qué cuota se miden los porcentajes?

Contra una fórmula a nivel de app que Meta publica entera: Calls within one hour = 200 * Number of Users.

El multiplicador es fijo y el multiplicando es la interacción. Meta lo define como "the number of unique daily active users an app has", con una reserva para el tráfico desigual: "In cases where there are slow periods of daily usage, such as if your app has high activity on weekends but low activity over weekdays, the weekly and monthly active Users are used to calculate the number of Users for your app." Las instalaciones no entran en la cuenta. Meta lo dice directamente: las apps con mucha interacción diaria reciben límites más altos "regardless of the actual number of app installs."

La bolsa es compartida, no repartida. Meta hace la aritmética por su cuenta: "if your app has 100 Users, your app can make 20,000 calls per hour. However, your top ten most engaged Users could make 19,000 of those calls." Una sola cuenta ruidosa puede dejar sin nada al resto de usuarios de una app dentro de la misma hora, y nada en el límite de Platform lo impide.

Los tokens de usuario llevan un segundo recuento, aparte, que ninguna cabecera informa. El recuento de llamadas del propio usuario corre en su propia hora móvil y abarca todas las apps que usa, así que Meta advierte de que un usuario "could make X calls through App1 and Y calls through App2" y quedar limitado por el total. Después cierra la puerta a medirlo: "Due to privacy concerns, we do not reveal actual call count values for users." No existe ninguna cabecera x-user-usage. El lado de usuario de los Platform Rate Limits es inobservable por diseño.

Hay una regla de conteo que pilla a quien agrupa solicitudes. Las FAQ de Meta indican que "each ID counts as one API call" y lo demuestran: tres solicitudes separadas de un ID cuentan como tres llamadas, y una sola solicitud con ids=4,5,6 también cuenta como tres. Agrupar mejora el rendimiento de la respuesta y no compra cuota. Ese es un modelo de contabilidad distinto del de los techos de solicitudes por endpoint que publica Bluesky y del de la división de Pinterest entre techos a nivel de app y de usuario.

¿En qué se diferencia x-app-usage de la cabecera de business use case?

Distinto alcance, distinta forma, y una de las dos te dice cuándo vuelves a entrar.

La cabecera de business use case es la más rica de las dos, y es la que importa para el trabajo de publicación en Instagram. La fórmula de 4800 por impresiones de Meta y los campos de X-Business-Use-Case-Usage se cubren a fondo aparte, incluidos los valores de type y los códigos de error asociados a cada uno.

Donde las dos cabeceras se tocan, el propio documento de Meta se contradice. La sección de Platform pega el paréntesis "(for v3.3 and older Ads API calls)" a X-Ad-Account-Usage, que es lo que describe. La sección de business use case repite después ese mismo paréntesis en otra cabecera distinta: "All API responses made by your app that are rate limited using the BUC logic include an X-Business-Use-Case-Usage (for v3.3 and older Ads API calls) HTTP header." La cabecera de business use case no está restringida a llamadas v3.3 y anteriores, y el resto de esa misma sección la documenta como el mecanismo actual para el tráfico de Instagram y de la Marketing API. Trata el matiz como un artefacto de copiar y pegar.

La regla de precedencia entre las dos es la única línea que vale la pena memorizar: "If both Platform and Business Use Case rate limits can be applied to a request, BUC rate limits will be applied."

¿Qué pasa cuando x-app-usage marca 100?

Las llamadas empiezan a fallar con un error numerado, y qué número depende de a quién se le rompió el límite.

La indicación de Meta para todos ellos es la misma y no es una política de reintentos: "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."

Esa es la frase que la mayoría de los bucles de reintento interpreta mal. El backoff exponencial sigue enviando solicitudes, y según Meta cada una aleja más el momento del desbloqueo. La respuesta correcta al código de error 4 es aparcar la cola, no ralentizarla.

Y luego llega el hueco. La propia buena práctica de Meta para recuperarse dice: "Check the X-App-Usage HTTP header to see how close your app is to its limit and when you can resume making calls when the limit has been reached." La cabecera tiene tres campos, todos porcentajes, y ninguno es un tiempo. estimated_time_to_regain_access existe en la cabecera de business use case. reset_time_duration existe en X-Ad-Account-Usage. Ninguno existe en x-app-usage. Meta te dice que leas una hora de reanudación en una cabecera que no la lleva.

Lo que recibes en su lugar es el App Dashboard, donde Meta muestra "the app's current Application Rate Limits usage percentage" y la actividad media de los últimos siete días. Eso es un gráfico para humanos, no un campo que tu lógica de reintento pueda leer. El enfoque práctico es ver subir call_count, parar bastante antes de 100 y repartir el tráfico de forma uniforme, que también es el consejo declarado de Meta: "Spread out queries evenly to avoid traffic spikes." Los calendarios de publicación también chocan con los techos aparte y sin numerar, y los límites diarios de publicación de Facebook son su propio sistema con su propio comportamiento.

Preguntas frecuentes

¿Cuáles son los tres campos de la cabecera x-app-usage?

call_count, total_cputime y total_time. Meta define cada uno como un número entero que expresa un porcentaje: de las llamadas hechas en una hora móvil y del tiempo de CPU y del tiempo total asignados al procesamiento de consultas.

¿Cuál es el límite de tasa de la Graph API a nivel de app que hay detrás de call_count?

Calls within one hour = 200 * Number of Users, donde el número de usuarios es el recuento que hace Meta de usuarios activos diarios únicos de la app, con vuelta a los activos semanales y mensuales cuando el tráfico diario es desigual.

¿Qué código de error significa que se alcanzó el límite de x-app-usage?

El código de error 4, que Meta llama "API Too Many Calls". El código 17 cubre el límite propio del usuario, y el código 32 cubre las llamadas a la Pages API hechas con un token de acceso de usuario o de aplicación.

¿Dice x-app-usage cuándo termina el bloqueo?

No. Lleva tres porcentajes y ningún campo de tiempo, aunque las buenas prácticas de Meta te digan que la consultes para saber cuándo puedes reanudar. estimated_time_to_regain_access pertenece a la cabecera de business use case, no a esta.

¿Aparece la cabecera x-app-usage en todas las respuestas?

No. Meta la devuelve en endpoints "that receive enough requests from your app", así que una cabecera ausente no lleva ninguna información y nunca debe leerse como uso cero.

¿Qué solicitudes reciben x-app-usage en lugar de X-Business-Use-Case-Usage?

Las solicitudes de la Graph API bajo Platform Rate Limits. Las solicitudes de la Marketing API y de Instagram Platform reciben la cabecera de business use case, y donde podrían aplicarse las dos, Meta indica que ganan los límites de business use case.

¿Qué cuenta como usuario en la fórmula 200 veces usuarios?

Meta lo define como el número de usuarios activos diarios únicos que tiene la app. Cuando el tráfico diario varía entre semana y fin de semana, se usan en su lugar los usuarios activos semanales y mensuales. Las instalaciones no entran en la cuenta, ya que las apps con alto engagement obtienen límites más altos sin importar el número real de instalaciones.

¿Puede un solo usuario agotar todo el límite de una app?

Un usuario muy activo puede hacerlo. La propia Meta hace el cálculo: una app con 100 usuarios tiene un cupo de 20.000 llamadas por hora, y los diez usuarios más activos podrían generar 19.000 de esas llamadas. El cupo se comparte en lugar de repartirse, así que nada en el límite de Platform impide que una sola cuenta deje sin cuota al resto de usuarios de la app dentro de la misma hora.

¿Agrupar varios IDs en una sola solicitud ahorra cuota de límite de tasa?

Agrupar no reduce lo que cuenta contra la cuota. El FAQ de Meta indica que cada ID cuenta como una llamada a la API, así que tres solicitudes separadas de un solo ID y una solicitud con ids=4,5,6 cuentan igual, como tres llamadas. El batching mejora el rendimiento de la respuesta, no el presupuesto.

¿En qué se diferencia x-app-usage de X-Ad-Account-Usage?

X-Ad-Account-Usage reporta su campo acc_id_util_pct con decimales, mostrado en el ejemplo de Meta como 9,67, mientras que cada campo de x-app-usage se redondea a un porcentaje entero. X-Ad-Account-Usage también incluye reset_time_duration, un campo que x-app-usage no tiene, y la cabecera está ligada a las llamadas de la API de Ads de la versión 3.3 y anteriores.