Três porcentagens e nenhum relógio no cabeçalho x-app-usage da Meta

O que é o cabeçalho x-app-usage?

Nas respostas da Graph API, o cabeçalho x-app-usage da Meta informa ao app quanto do próprio limite de taxa ele já gastou. A referência de limites de taxa o apresenta em uma 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."

Duas condições se escondem nessa frase. O cabeçalho pertence ao app, não à conta nem ao usuário cujo token fez a chamada. E ele só chega em endpoints que viram tráfego suficiente, algo que a Meta reafirma em outro ponto como cabeçalhos "included with most API responses once enough calls have been made to an endpoint." Uma resposta sem x-app-usage significa que a Meta preferiu não informar, não que o uso seja zero.

O valor é um objeto JSON com três chaves e nada mais. O exemplo da própria 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
}

Quais requisições recebem esse cabeçalho em vez de outro depende da API e do token. A Meta separa com clareza: "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." Chamadas da Pages API caem de um lado ou de outro conforme a credencial, com tokens de aplicativo e de usuário do lado Platform e tokens de usuário de sistema ou de Página do lado business use case.

O que significam os três campos do x-app-usage?

Todos os três são porcentagens de uma franquia, não contagens de coisa alguma.

A palavra "whole" está trabalhando de verdade ali. Todo valor do x-app-usage é inteiro, então a leitura mais fina que você consegue é um por cento do orçamento. O outro cabeçalho de nível de app da Meta é mais preciso sobre a mesma ideia: o campo acc_id_util_pct em X-Ad-Account-Usage aparece no exemplo como 9.67, com decimais. O x-app-usage arredonda.

Os três campos também limitam de forma independente. A Meta anexa as mesmas duas linhas aos dois campos de tempo: "When total_cputime reaches 100, calls may be throttled" e "When total_time reaches 100, calls may be throttled." Um punhado de consultas caras pode empurrar o total_cputime para perto do teto enquanto o call_count ainda está na casa de um dígito, então um app que só observa volume de chamadas perde de vista duas das três formas de ser bloqueado.

Repare no que a Meta não publica ali. A referência declara um limiar para total_cputime e um limiar para total_time e nunca escreve a frase correspondente para call_count na seção de cabeçalhos Platform. O que ela diz no lugar é genérico: "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." Leia 100 no call_count como o limite mesmo assim, porque nada no documento sugere outro número.

Contra qual franquia as porcentagens são medidas?

Uma fórmula de nível de app que a Meta publica por inteiro: Calls within one hour = 200 * Number of Users.

O multiplicador é fixo e o multiplicando é engajamento. A Meta o define como "the number of unique daily active users an app has", com uma saída para tráfego irregular: "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." Instalações não entram na conta. A Meta diz isso diretamente: apps com alto engajamento diário recebem limites maiores "regardless of the actual number of app installs."

O bolo é compartilhado, não dividido. A própria Meta faz a aritmética: "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." Uma conta barulhenta pode matar de fome o resto dos usuários do app dentro da mesma hora, e nada no limite Platform impede isso.

Tokens de usuário carregam uma segunda contagem, separada, que nenhum cabeçalho reporta. A contagem de chamadas do próprio usuário roda em uma hora móvel própria e atravessa todos os apps que ele usa, então a Meta avisa que um usuário "could make X calls through App1 and Y calls through App2" e pode ser limitado pelo total. Em seguida ela fecha a porta para medir isso: "Due to privacy concerns, we do not reveal actual call count values for users." Não existe cabeçalho x-user-usage. O lado do usuário nos Platform Rate Limits é inobservável por projeto.

Uma regra de contagem pega quem usa lote. O FAQ da Meta afirma que "each ID counts as one API call" e demonstra: três requisições separadas de um ID cada contam como três chamadas, e uma requisição com ids=4,5,6 também conta como três. Agrupar melhora o desempenho da resposta e não compra cota nenhuma. É um modelo de contabilidade diferente dos tetos de requisição por endpoint que o Bluesky publica e da separação do Pinterest entre tetos de app e de usuário.

Qual a diferença entre o x-app-usage e o cabeçalho de business use case?

Escopo diferente, formato diferente, e um dos dois diz quando você volta.

O cabeçalho de business use case é o mais rico dos dois e é o que importa no trabalho de publicação no Instagram. A fórmula de 4800 vezes as impressões da Meta e os campos do X-Business-Use-Case-Usage estão detalhados em outro texto, inclusive os valores de type e os códigos de erro ligados a cada um.

No ponto em que os dois cabeçalhos se encostam, o documento da própria Meta se contradiz. A seção Platform anexa o parêntese "(for v3.3 and older Ads API calls)" ao X-Ad-Account-Usage, que é o que ela descreve. A seção de business use case então repete o mesmo parêntese em outro cabeçalho: "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." O cabeçalho de business use case não está restrito a chamadas v3.3 e anteriores, e o resto daquela mesma seção o documenta como o mecanismo atual para tráfego de Instagram e Marketing API. Trate a ressalva como um artefato de copiar e colar.

A regra de precedência entre os dois é a linha que vale memorizar: "If both Platform and Business Use Case rate limits can be applied to a request, BUC rate limits will be applied."

O que acontece quando o x-app-usage marca 100?

As chamadas começam a falhar com um erro numerado, e o número depende de qual limite estourou.

A orientação da Meta para todos eles é a mesma e não é uma política de backoff: "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."

É essa a frase que a maioria dos laços de retentativa erra. Backoff exponencial continua enviando requisições e, pela conta da Meta, cada uma empurra o desbloqueio para mais longe. A resposta correta ao código de erro 4 é estacionar a fila, não desacelerá-la.

Aí vem a lacuna. A boa prática da própria Meta para se recuperar diz: "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." O cabeçalho tem três campos, todos porcentagens, e nenhum deles é um tempo. estimated_time_to_regain_access existe no cabeçalho de business use case. reset_time_duration existe no X-Ad-Account-Usage. Nenhum dos dois existe no x-app-usage. A Meta manda ler um horário de retomada em um cabeçalho que não carrega horário nenhum.

O que você recebe no lugar é o App Dashboard, onde a Meta mostra "the app's current Application Rate Limits usage percentage" e a atividade média dos últimos sete dias. Isso é um gráfico para humanos, não um campo que a sua lógica de retentativa consiga ler. O caminho prático é observar o call_count subir, parar bem antes dos 100 e distribuir o tráfego de forma uniforme, que é também o conselho declarado da Meta: "Spread out queries evenly to avoid traffic spikes." Calendários de publicação esbarram também nos tetos separados e sem número, e os limites diários de postagem do Facebook são um sistema próprio, com comportamento próprio.

Perguntas frequentes

Quais são os três campos do cabeçalho x-app-usage?

call_count, total_cputime e total_time. A Meta define cada um como um número inteiro que expressa uma porcentagem, das chamadas feitas em uma hora móvel e do tempo de CPU e do tempo total alocados para processar consultas.

Qual é o limite de taxa da Graph API no nível do app por trás do call_count?

Calls within one hour = 200 * Number of Users, em que o número de usuários é a contagem da Meta de usuários ativos diários únicos do app, caindo para ativos semanais e mensais quando o tráfego diário é irregular.

Qual código de erro indica que o limite do x-app-usage estourou?

O código de erro 4, que a Meta chama de "API Too Many Calls". O código 17 cobre o limite do próprio usuário e o código 32 cobre chamadas da Pages API feitas com token de usuário ou de aplicativo.

O x-app-usage diz quando o bloqueio acaba?

Não. Ele carrega três porcentagens e nenhum campo de tempo, mesmo com as boas práticas da Meta mandando consultá-lo para saber quando retomar. estimated_time_to_regain_access pertence ao cabeçalho de business use case, não a esse.

O cabeçalho x-app-usage aparece em toda resposta?

Não. A Meta o devolve em endpoints "that receive enough requests from your app", então um cabeçalho ausente não carrega informação nenhuma e nunca deve ser lido como uso zero.

Quais requisições recebem x-app-usage em vez de X-Business-Use-Case-Usage?

Requisições da Graph API sob Platform Rate Limits. Requisições da Marketing API e da Instagram Platform recebem o cabeçalho de business use case e, onde os dois poderiam valer, a Meta afirma que os limites de business use case vencem.

O que conta como usuário na fórmula 200 vezes usuários?

A Meta define isso como o número de usuários ativos diários únicos de um app. Quando o tráfego diário varia entre dias úteis e fim de semana, os usuários ativos semanais e mensais são usados no lugar disso. As instalações não entram nessa conta, já que apps com alto engajamento recebem limites mais altos independentemente do número real de instalações.

Um único usuário pode consumir todo o limite de taxa de um app?

Um usuário bastante ativo pode. A própria Meta faz a conta: um app com 100 usuários tem uma cota de 20.000 chamadas por hora, e os dez usuários mais engajados poderiam gerar 19.000 dessas chamadas. A cota é compartilhada em vez de dividida, então nada no limite de Platform impede que uma única conta deixe o resto dos usuários do app sem cota na mesma hora.

Agrupar vários IDs em uma única requisição economiza cota de rate limit?

Agrupar não reduz o que conta contra a cota. O FAQ da Meta afirma que cada ID conta como uma chamada de API, então três requisições separadas de um único ID e uma requisição com ids=4,5,6 contam igual, como três chamadas. O batching melhora a performance da resposta, não o orçamento.

Qual a diferença entre x-app-usage e X-Ad-Account-Usage?

O X-Ad-Account-Usage reporta seu campo acc_id_util_pct com casas decimais, mostrado no exemplo da Meta como 9,67, enquanto todo campo do x-app-usage é arredondado para uma porcentagem inteira. O X-Ad-Account-Usage também traz reset_time_duration, um campo que o x-app-usage não tem, e o cabeçalho está atrelado a chamadas da API de Ads na versão 3.3 e anteriores.