Limitação de volume na Graph API

A limitação de volume na Graph API do Facebook só deve ser encontrada em circunstâncias raras. Este documento descreve quais são esses limites e como lidar com eles.

Há dois tipos principais de limitação de volume que podem ser encontrados por seu aplicativo: a limitação de volume no nível de aplicativo e a limitação de volume no nível de página.

Limitação de volume no nível de aplicativo

Esses limites se aplicam às chamadas feitas por meio de qualquer token de acesso diferente de um token de acesso de página. Seu aplicativo receberá um código de erro 4 se você atingir esses limites.

Painel de limitação de volume

Você pode consultar os gráficos da atividade de limitação de volume do seu aplicativo no painel de aplicativos do seu aplicativo.

Limites

As limitações de volume são impostas em cada aplicativo. A ferramenta de limitação de volume apresenta informações sobre o quanto seu aplicativo está próximo de ser limitado. Clique em qualquer exemplo para receber mais detalhes sobre os tipos de utilização.

Seu aplicativo pode fazer 200 chamadas por hora por usuário de forma agregada. Por exemplo, se o seu aplicativo tiver 100 usuários, isso significa que ele poderá fazer 20.000 chamadas. Não se trata de uma limitação por usuário, portanto um usuário poderia fazer 19.000 dessas chamadas e outro poderia fazer 1.000. Esse limite é calculado com base no número de chamadas feitas na hora anterior.

Se o seu aplicativo tiver uma limitação de volume, todas as chamadas para esse aplicativo serão limitadas, não somente as de um usuário específico.

O número de usuários do aplicativo é calculado como a média de usuários ativos diários, mais os novos logins do dia como uma estimativa de valor. Os aplicativos com uma grande quantidade de usuários podem ter uma limitação de volume mais precisa do que os aplicativos com um número menor de usuários. Os aplicativos com uma quantidade muito pequena de usuários podem apresentar problemas de limite de volume.

Advertências:

  • nem todas as chamadas à API ficam sujeitas à limitação de volume, então o número de chamadas que você fizer poderá não corresponder ao que estiver visível na ferramenta de limitação de volume.
  • O Facebook também limita as chamadas com base no tempo de uso da CPU e no tempo total. É difícil atingir esses limites, trata-se de uma ocorrência extremamente rara. Essa informação é exposta no painel de detalhes de cada exemplo. Clique no gráfico, na ferramenta de limitação de volume do painel, para ver mais detalhes.
  • A API de Informações de Anúncios e a API de Marketing podem usar um conjunto diferente de limitação de volume. Consulte o documento sobre Limitação de volume da API de Marketing em https://developers.facebook.com/docs/marketing-api/api-rate-limiting para ver mais informações sobre a API de Marketing.

Recomendações

A limitação do volume define os limites de quantas chamadas à API podem ser feitas em um intervalo de tempo específico. Se a limitação de volume for excedida, todas as chamadas à API de um aplicativo serão limitadas e poderão falhar por um breve intervalo de tempo. Se um aplicativo for limitado, o autor da chamada receberá uma mensagem de erro error code = 4, CodedException nas chamadas seguintes. Pode demorar até uma hora para que suas solicitações sejam aceitas novamente.

Para evitar a limitação de volume, recomendamos:

  • Dividir as consultas de forma uniforme entre dois intervalos de tempo para evitar o envio de tráfego como picos.
  • Usar filtros para limitar o tamanho da resposta de dados e evitar chamadas que solicitem dados sobrepostos.
  • Use o cabeçalho de limitação de volume para equilibrar de forma dinâmica o volume da sua chamada.

Cabeçalho de limitação de volume

Se o seu aplicativo estiver fazendo chamadas suficientes para ser considerado na limitação de volume por nosso sistema, retornaremos um cabeçalho HTTP X-App-Usage. Este cabeçalho contém a porcentagem atual de uso do seu aplicativo. Esse percentual é igual ao uso informado no gráfico de limitação de volume. Use esse número para equilibrar de forma dinâmica a sua carga de chamadas para evitar a limitação.

O cabeçalho de limitação de volume é uma cadeia de caracteres no formato JSON na seguinte forma:

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

Os valores de x, y e z são números inteiros, que representam os valores percentuais usados para cada uma das métricas. Se uma dessas métricas exceder 100, o aplicativo sofrerá a limitação de volume.

Limitação de volume no nível de página

Esses limites se aplicam às chamadas feitas com token de acesso de página. Seu aplicativo receberá um código de erro 32 se você atingir esses limites.

A publicação do blog em https://developers.facebook.com/blog/post/2016/06/16/page-level-rate-limits/ apresenta uma explicação detalhada da limitação de volume no nível de página.

Painel de limitação de volume

Para cada página cujo token de acesso for usado pelo seu aplicativo para fazer chamadas, você poderá consultar os gráficos de limitação de volume dessa página.

Limites

As limitações de volume serão impostas a cada página, no lugar do aplicativo. A ferramenta de limitação de volume lhe dará informações sobre quantos aplicativos usam o token de acesso dessa página e o quão próximo a página se encontra de ser limitada. Clique em qualquer exemplo para receber mais detalhes sobre os tipos de utilização.

O número de pessoas envolvidas diariamente com o uso de uma página é o número de pessoas que interagiram com a página durante um período de 24 horas. Uma interação com uma página consiste em um clique na página ou em seu conteúdo.

O número de usuários envolvidos nas 24 horas anteriores será usado para calcular os limites de volume da janela atual de 24 horas.

Pode ser feito um total de 4.800 chamadas por usuários envolvidos diariamente em nome da página por 24 horas no conjunto. Por exemplo, se a página tiver 100 usuários envolvidos diariamente, poderão ser feitas 480.000 chamadas em nome da página em um período de 24 horas. Esse período de 24 horas é uma janela variável, atualizada uma vez a cada período de alguns minutos. Essa limitação de chamadas é um limite por página, então um aplicativo poderia fazer 400.000 chamadas e outro poderia fazer 80.000. Se uma página sofrer limitação de volume, somente as chamadas do aplicativo que estiverem usando o token de acesso dessa página serão limitados. Isso significa que o seu aplicativo continuará funcionando normalmente para outras chamadas.

O número de chamadas para sua página é calculado como o número estimado de chamadas usando seu token de acesso por dia. As páginas com uma quantidade maior de chamadas por dia podem ter uma limitação de taxa mais precisa do que as páginas com um número menor de chamadas. As páginas com uma quantidade muito pequena de chamadas por dia podem apresentar problemas de limite de taxa.

Advertências:

  • nem todas as chamadas à API ficam sujeitas à limitação de volume, então o número de chamadas que você fizer poderá não corresponder ao que estiver visível na ferramenta de limitação de volume.
  • O Facebook também limita as chamadas com base no tempo de uso da CPU e no tempo total. Clique no gráfico, na ferramenta de limitação de volume do painel, para ver mais detalhes.
  • A API de Informações de Anúncios e a API de Marketing podem usar um conjunto diferente de limitação de volume. Consulte o Documento de limitação de volume da API de Marketing para saber mais sobre a API de Marketing.

Recomendações

Se uma página for limitada, o autor da chamada receberá uma mensagem de erro error code = 32, CodedException nas chamadas seguintes. Poderá demorar até uma hora para que suas solicitações a essa página sejam aceitas novamente.

Para evitar a limitação de volume, recomendamos:

  • Dividir as consultas de forma uniforme entre dois intervalos de tempo para evitar o envio de tráfego como picos.
  • Usar filtros para limitar o tamanho da resposta de dados e evitar chamadas que solicitem dados sobrepostos.
  • Use o cabeçalho de limitação de volume para equilibrar de forma dinâmica o volume da sua chamada.

Cabeçalho de limitação de volume

Se estiverem sendo feitas chamadas suficientes em nome dessa página para que ela seja considerada na limitação de volume por nosso sistema, retornaremos um cabeçalho HTTP X-Page-Usage. Este cabeçalho contém a porcentagem atual de uso da página. Se você fizer chamadas usando o token de acesso de uma página, você receberá o valor X-Page-Usage somente dessa página. Essa porcentagem é igual à utilização apresentada no gráfico de limitação de volume dessa página. Use esse número para equilibrar de forma dinâmica a sua carga de chamadas para evitar a limitação.

O cabeçalho de limitação de volume é uma cadeia de caracteres no formato JSON na seguinte forma:

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

Os valores de x, y e z são números inteiros, que representam os valores percentuais usados para cada uma das métricas. Se uma dessas métricas exceder 100, o aplicativo sofrerá a limitação de volume.

Limitação de volume no nível da conta

Esses limites se aplicam às chamadas feitas com tokens de acesso do usuário. Seu aplicativo receberá o código de erro 17 se este limite for atingido. Isso ocorre quando uma conta de usuário específica está realizando muitas chamadas na API.

Observação:

isso pode incluir chamadas do usuário realizadas por vários aplicativos, não apenas o seu.

Quando um usuário tem a taxa limitada, as chamadas de API dos usuários são limitadas.

Para evitar a limitação de volume, recomendamos:

Não há nada que você possa fazer para impedir isso. O usuário está realizando muitas chamadas (possivelmente por outros aplicativos) e, portanto, obtendo uma taxa limitada. No entanto, se isso está acontecendo para muitos usuários de um aplicativo, provavelmente as chamadas de API realizadas por esse aplicativo estão causando isso. Nesse caso, você deve reduzir as chamadas ou espalhar de forma mais uniforme.

Perguntas frequentes

O que consideramos uma chamada à API?

Todas as chamadas entrarão na contagem da limitação de volume, não apenas solicitações HTTPS individuais à API. Por exemplo, você pode fazer uma única chamada à API e especificar vários ids, mas cada ID contaria como sua própria chamada à API, mesmo que você estivesse fazendo apenas uma solicitação HTTPS à API.

Para ilustrar esse conceito, veja os exemplos abaixo:

Solicitações de exemplo Número de chamadas à 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

Em um cenário no qual for preciso percorrer vários objetos por ID, recomendamos o uso da segunda abordagem, pois isso aprimorará o desempenho de suas respostas da API, mas não aprimorará o número de chamadas feitas a fim de atender aos propósitos da limitação de volume.

Você também pode usar a API de Lote para agrupar suas solicitações em lotes, mas observe que cada subsolicitação é sua própria chamada à API, ou mesmo múltiplas chamadas à API no caso da especificação de muitos IDs.

Se o seu aplicativo ou sua página sofrer limitação de volume, as chamadas à API limitadas também entrarão na contagem de sua limitação de volume.

Quais erros meu aplicativo receberá?
Tipo de limitação No mínimo Código de erro

Limitação no nível de aplicativos

200 chamadas/pessoa/hora

4

Limitação no nível da conta

Não aplicável

17

Limitação no nível de página

4800 chamadas/pessoa/24 horas

32

Limitação a nível personalizado

Não aplicável

613

Estou vendo o Código de Erro 613. O que devo fazer?

Seu aplicativo está excedendo um limite de taxa personalizado. Fale com seu gerente de conta para que ele o ajude a resolver este problema.

Estou criando um desmembrador, devo me preocupar com algo mais?

Se você estiver criando um serviço que extrai dados, convém examinar nossos termos de extração.