Limites de volume

Um limite de volume é o número de chamadas de API que um app ou usuário pode fazer dentro de um determinado intervalo de tempo. Se esse limite ou os limites de CPU e de tempo total forem excedidos, o app ou o usuário poderá ser limitado. As solicitações da API feitas por esse app ou usuário apresentarão falha.

Todas as solicitações da API estão sujeitas à limitação de volume. As solicitações da Graph API e da API de Exibição Básica do Instagram estão sujeitas aos limites de volume da plataforma. Já as solicitações da API de Marketing e da Graph API do Instagram estão sujeitas aos limites de volume de casos de uso de empresas (BUC, pelas iniciais em inglês).

As solicitações da API de Páginas estão sujeitas aos limites de volume da plataforma ou de BUC, dependendo do token usado na solicitação. As solicitações feitas com tokens de acesso do app ou tokens de acesso do usuário estão sujeitas aos limites de volume da plataforma. Já as solicitações feitas com tokens de acesso do usuário do sistema ou tokens de acesso à Página estão sujeitas aos limites de volume do caso de uso da empresa.

As estatísticas de uso do limite de volume em tempo real são descritas em cabeçalhos incluídos na maioria das respostas de API depois que chamadas suficientes tenham sido feitas a um ponto de extremidade. As estatísticas de uso do limite de volume da plataforma também são exibidas no Painel de Apps. Depois de o limite de volume ser atingido, qualquer solicitação subsequente feita pelo app falhará. A API retornará um código de erro até passar tempo suficiente para que a contagem de chamadas fique abaixo do limite.

Quando for possível aplicar os limites de volume de casos de uso de empresas e os da plataforma, os da empresa serão implementados.

Limites de volume da plataforma

Os limites de volume da plataforma são monitorados no nível do usuário ou do app individual, dependendo do tipo de token utilizado na solicitação.

Apps

As solicitações da Graph API feitas com um token de acesso do app são computadas conforme o limite de volume do app. A contagem de chamadas de um app é o número de chamadas que ele pode fazer durante o período de 1 hora. O cálculo é feito da seguinte forma:

Number of Users se baseia na quantidade de usuários ativos diários exclusivos do app. Em casos com períodos lentos de uso diário (por exemplo, se o app tem alta atividade nos finais de semana, mas atividade baixa nos dias de semana), os usuários ativos semanais ou mensais serão usados para calcular o número de usuários do app. Os apps com alto engajamento diário terão limites de volume maiores do que aqueles com baixo engajamento diário, independentemente do número real de instalações do app.

Lembre-se de que esse limite não é por usuário, mas por chamadas feitas pelo app. Qualquer usuário individual pode fazer mais de 200 chamadas por hora, desde que o total de chamadas do app não exceda o limite. Por exemplo, se tiver 100 usuários, o app poderá fazer 20 mil chamadas por hora. Porém, os 10 usuários mais engajados podem fazer 19 mil dessas chamadas.

Usuários

As solicitações da Graph API feitas com um token de acesso de usuário são computadas conforme a contagem de chamadas do usuário. A contagem de chamadas de um usuário é o número de chamadas que ele pode fazer durante o período de 1 hora. Devido a preocupações com privacidade, não revelamos os valores reais da contagem de chamadas para os usuários.

Lembre-se de que a contagem de chamadas de um usuário pode ser distribuída entre diversos apps. Por exemplo, o usuário pode fazer X chamadas no App 1 e Y chamadas no App 2. Se X+Y exceder a contagem de chamadas do usuário, ele terá o volume limitado. Isso não significa que o app está fazendo algo errado. Talvez o usuário esteja usando vários apps ou usando a API de forma incorreta.

Cabeçalhos

Os pontos de extremidade que receberem solicitações suficientes do app incluirão um cabeçalho HTTP X-App-Usage ou X-Ad-Account-Usage (para chamadas da API de Anúncios versão 3.3 e anteriores) nas respostas. O cabeçalho terá uma string formatada em JSON que descreve o uso do limite de volume atual do app.

Conteúdo do cabeçalho

Conteúdo do cabeçalho X-Ad-Account-Usage

Tempo total de CPU

A quantidade de tempo de CPU para a solicitação ser processada. Quando o total_cputime chega a 100, as chamadas podem ser limitadas.

Tempo total

A quantidade de tempo para a solicitação ser processada. Quando o total_time chega a 100, as chamadas podem ser limitadas.

Exemplo do valor do cabeçalho X-App-Usage

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
}

Exemplo do valor do cabeçalho X-Ad-Account-Usage

x-ad-account-usage: {
    "acc_id_util_pct": 9.67,   //Percentage of calls made for this ad account.
    "reset_time_duration": 100,   //Time duration (in seconds) it takes to reset the current rate limit score.
    "ads_api_access_tier": 'standard_access'   //Tiers allows your app to access the Marketing API. standard_access enables lower rate limiting.
}

Painel

O Painel de Apps exibe o número de usuários do app com o volume limitado, o percentual de uso atual dos limites de volume do app, além de mostrar a atividade média nos últimos 7 dias. No cartão Limite de volume do aplicativo, clique em Ver detalhes e passe o ponteiro do mouse sobre um ponto no gráfico para ver mais detalhes sobre o uso naquele momento específico. Como o uso depende do volume de chamadas, talvez o gráfico não mostre um período completo de 7 dias. Os apps com volume maior de chamadas mostrarão mais dias.

Códigos de erro

Quando um app ou usuário atingir o limite de volume, as solicitações feitas por ele serão preenchidas, e a API responderá com um código de erro.

Códigos de erro de limitações

Exemplo de resposta

{
  "error": {
    "message": "(#32) Page request limit reached",
    "type": "OAuthException",
    "code": 32,
    "fbtrace_id": "Fz54k3GZrio"
  }
}

Códigos de limitação da estabilidade do Facebook

Boas práticas

• Quando o limite tiver sido atingido, pare de fazer chamadas à API. Se você seguir fazendo chamadas, a contagem delas continuará aumentando. Com isso, levará ainda mais tempo para que as chamadas voltem a ser bem-sucedidas.
• Espalhe as consultas de maneira uniforme para evitar picos de tráfego.
• Use filtros para limitar o tamanho da resposta de dados e evite chamadas que solicitem dados sobrepostos.
• Verifique o cabeçalho HTTP X-App-Usage para ver se a conta de anúncios está próxima do limite e quando você poderá voltar a fazer chamadas, caso o limite tenha sido atingido.
• Se os usuários estiverem limitados, verifique se o seu app não é a causa. Reduza as chamadas do usuário ou espace-as de maneira uniforme ao longo do tempo.

Limites de volume de casos de uso de empresas

Todas as solicitações da API de Marketing e da API de Páginas feitas com um token de acesso de sistema ou um token de acesso à Página estão sujeitas aos limites de volume de casos de uso de empresas (BUC, pelas iniciais em inglês) e dependem dos pontos de extremidade sendo consultados.

Para a API de Marketing, o limite de volume é aplicado à conta de anúncios no mesmo caso de uso da empresa. Por exemplo, todos os pontos de extremidade com caso de uso do Gerenciamento de Anúncios compartilharão a cota total na mesma conta de anúncios. Se um ponto de extremidade fizer um número excessivo de solicitações de API, outros pontos de extremidade configurados com o mesmo caso de uso da empresa também receberão erros referentes à limitação de volume. A cota depende do nível de acesso da API de Marketing do app. O nível de acesso padrão da API de Marketing terá mais cotas do que o nível de acesso de desenvolvimento. Por padrão, um novo app deve estar no nível de desenvolvimento. Se você precisar obter mais cota de limitação de volume, atualize o Acesso Padrão ao Gerenciamento de Anúncios para o acesso avançado na análise do app.

Insights sobre Anúncios

As solicitações feitas pelo seu app à API de Insights sobre Anúncios são contabilizadas para as métricas de limite de volume, como número de chamadas, tempo total de CPU e tempo total. A contagem de chamadas de um app é o número de chamadas que ele pode fazer durante o período de 1 hora. O cálculo é feito da seguinte forma:

Para apps com acesso padrão ao recurso Acesso Padrão ao Gerenciamento de Anúncios:

Para apps com acesso avançado ao recurso Acesso Padrão ao Gerenciamento de Anúncios:

Number of Active ads é o número de anúncios veiculados no momento por conta de anúncios. User Erros é a quantidade de erros recebidos ao fazer uma chamada de API. Para obter um limite de volume mais alto, inscreva-se no recurso Acesso Padrão ao Gerenciamento de Anúncios.

Essa limitação também pode estar sujeita ao tempo total de CPU e ao tempo total de processamento durante o período de 1 hora. Para mais detalhes, verifique o cabeçalho HTTP X-Business-Use-Casetotal_cputime e total_time.

Se estiver recebendo erros de limitação de volume, você também pode consultar estimated_time_to_regain_access no cabeçalho X-Business-Use-Case para ver o tempo de bloqueio estimado.

Gerenciamento de anúncios

As solicitações feitas pelo seu app à API de Gerenciamento de Anúncios são contabilizadas para as métricas de limite de volume, como número de chamadas, tempo total de CPU e tempo total. A contagem de chamadas de um app é o número de chamadas que ele pode fazer durante o período de 1 hora. O cálculo é feito da seguinte forma:

Para apps com acesso padrão ao recurso Acesso Padrão ao Gerenciamento de Anúncios:

Para apps com acesso avançado ao recurso Acesso Padrão ao Gerenciamento de Anúncios:

Number of Active Ads é o número de anúncios para cada conta de anúncios.

Essa limitação também pode estar sujeita ao tempo total de CPU e ao tempo total de processamento durante o período de 1 hora. Para mais detalhes, verifique o cabeçalho HTTP X-Business-Use-Casetotal_cputime e total_time.

Se estiver recebendo erros de limitação de volume, você também pode consultar estimated_time_to_regain_access no cabeçalho X-Business-Use-Case para ver o tempo de bloqueio estimado.

Catálogo

Lote de catálogos

As solicitações feitas pelo seu app são contabilizadas para as métricas de limite de volume, como número de chamadas, tempo total de CPU e tempo total durante o período de 1 hora para cada ID de catálogo. Esse cálculo é feito da seguinte forma:

Unique users é a quantidade de usuários únicos da empresa (em todos os catálogos) com intenção nos últimos 28 dias. Quanto mais usuários visualizam os produtos do catálogo, maior é a cota de chamadas alocada.

Gerenciamento de catálogos

As solicitações feitas pelo seu app são contadas em cada ID de catálogo com o número de chamadas que ele pode fazer durante o período de 1 hora. Esse cálculo é feito da seguinte forma:

Usuários únicos são usuários da empresa (em todos os catálogos) com intenção nos últimos 28 dias. Quanto mais usuários visualizam os produtos do catálogo, maior é a cota de chamadas alocada.

Essa fórmula se aplica a vários pontos de extremidade de catálogos.

Para ver informações adicionais sobre como obter a utilização do limite de volume atual, consulte Cabeçalhos.

Essa limitação também pode estar sujeita ao tempo total de CPU e ao tempo total de processamento durante o período de 1 hora. Para mais detalhes, verifique o cabeçalho HTTP X-Business-Use-Casetotal_cputime e total_time.

Se estiver recebendo erros de limitação de volume, você também pode consultar estimated_time_to_regain_access no cabeçalho X-Business-Use-Case para ver o tempo de bloqueio estimado.

Público personalizado

As solicitações feitas pelo seu app à API de Público Personalizado são contabilizadas para as métricas de limite de volume, como número de chamadas, tempo total de CPU e tempo total. A contagem de chamadas de um app é o número de chamadas que ele pode fazer durante o período de 1 hora. Esse cálculo nunca excederá 700.000 e é feito da seguinte forma:

Para apps com acesso padrão ao recurso Acesso Padrão ao Gerenciamento de Anúncios:

Para apps com acesso avançado ao recurso Acesso Padrão ao Gerenciamento de Anúncios:

Number of Active Custom Audiences é o número de públicos personalizados ativos para cada conta de anúncios.

Essa limitação também pode estar sujeita ao tempo total de CPU e ao tempo total de processamento durante o período de 1 hora. Para mais detalhes, verifique o cabeçalho HTTP X-Business-Use-Casetotal_cputime e total_time.

Se estiver recebendo erros de limitação de volume, você também pode consultar estimated_time_to_regain_access no cabeçalho X-Business-Use-Case para ver o tempo de bloqueio estimado.

Graph API do Instagram

As chamadas à Graph API do Instagram são computadas de acordo com a contagem de chamadas do app. A contagem de chamadas de um app, única para cada app e par de usuários, é o número de chamadas feitas durante uma janela de 24 horas. O cálculo é feito da seguinte forma:

Number of Impressions é o número de vezes que um conteúdo da conta do Instagram do usuário entrou na tela de uma pessoa nas últimas 24 horas.

Observações

• A API de Exibição Básica do Instagram usa os limites de volume da plataforma.
• A Descoberta de empresas e a Pesquisa de hashtag estão sujeitas aos limites de volume da plataforma.

Geração de cadastros

As solicitações feitas pelo app para a API de Geração de Cadastros são computadas conforme a contagem de chamadas do app. A contagem de chamadas de um app é o número de chamadas que ele pode fazer durante uma janela de 24 horas. Esse cálculo é feito da seguinte forma:

Number of Leads Generated é o número de cadastros gerados por Página para a conta de anúncios nos últimos 90 dias.

Plataforma do Messenger

Páginas

Os limites de volume da página podem usar a lógica do limite de volume da plataforma ou de BUC, dependendo do tipo de token. As chamadas à API de Páginas feitas com um token de acesso à Página ou um token de acesso do usuário do sistema usam o cálculo de limite de volume a seguir. As chamadas feitas com tokens de acesso do app ou tokens de acesso do usuário estão sujeitas aos limites de volume do usuário ou do app.

As solicitações feitas pelo app para a API de Páginas com um token de acesso à Página ou um token de acesso do usuário do sistema são computadas conforme a contagem de chamadas do app. A contagem de chamadas de um app é o número de chamadas que ele pode fazer durante uma janela de 24 horas. Esse cálculo é feito da seguinte forma:

Number of Engaged Users é o total de usuários que interagiram com a Página em 24 horas.

As solicitações feitas pelo app para a API de Páginas com um token de acesso do usuário ou um token de acesso do app seguem a lógica do limite de volume da plataforma.

Para evitar problemas de limitação de volume ao usar o recurso acesso ao conteúdo público da Página, recomendamos o uso de um token de acesso do usuário do sistema.

Gerenciador de efeito de comércio do Spark AR

As solicitações feitas pelo app para os pontos de extremidade do comércio são computadas conforme a contagem de chamadas do app. A contagem de chamadas de um app é o número de chamadas que ele pode fazer durante o período de 1 hora. O cálculo é feito da seguinte forma:

O número de catálogos é o total de catálogos em todas as contas de comércio gerenciadas pelo app.

API de Gerenciamento do WhatsApp Business

Cabeçalhos

Todas as respostas de API feitas pelo app que têm limitação de volume de BUC incluem um cabeçalho HTTP X-Business-Use-Case-Usage (para chamadas da API de Anúncios versão 3.3 e anteriores) com uma string formatada em JSON que descreve o uso atual do limite de volume de app. Esse cabeçalho pode retornar até 32 objetos em uma chamada.

Conteúdo do cabeçalho X-Business-Use-Case-Usage

Tempo total de CPU

A quantidade de tempo de CPU para a solicitação ser processada. Quando total_cputime chega a 100, as chamadas podem ser limitadas.

Tempo total

A quantidade de tempo para a solicitação ser processada. Quando total_time chega a 100, as chamadas podem ser limitadas.

Nível de acesso à API de Anúncios

Apenas para os tipos ads_insights e ads_management. Os níveis permitem que o app acesse a API de Marketing. Por padrão, os apps têm o nível development_access, e Standard_access habilita uma limitação de volume menor. Para aumentar o limite de volume e chegar ao nível padrão, você pode solicitar "acesso avançado" ao recurso Acesso Padrão ao Gerenciamento de Anúncios.

Exemplo do valor do cabeçalho X-Business-Use-Case-Usage

x-business-use-case-usage: {
    "{business-object-id}": [
        {
            "type": "{rate-limit-type}",           //Type of BUC rate limit logic being applied.
            "call_count": 100,                     //Percentage of calls made. 
            "total_cputime": 25,                   //Percentage of the total CPU time that has been used.
            "total_time": 25,                      //Percentage of the total time that has been used.   
            "estimated_time_to_regain_access": 19,  //Time in minutes to regain access.
            "ads_api_access_tier": "standard_access"  //Tiers allows your app to access the Marketing API. standard_access enables lower rate limiting.
        }
    ],      
    "66782684": [
        {
            "type": "ads_management",
            "call_count": 95,
            "total_cputime": 20,
            "total_time": 20,
            "estimated_time_to_regain_access": 0,
            "ads_api_access_tier": "development_access" 
        }
    ],
    "10153848260347724": [
        {
            "type": "ads_insights",
            "call_count": 97,
            "total_cputime": 23,
            "total_time": 23,
            "estimated_time_to_regain_access": 0,
            "ads_api_access_tier": "development_access"
        }
    ],
    "10153848260347724": [
        {
            "type": "pages",
            "call_count": 97,
            "total_cputime": 23,
            "total_time": 23,
            "estimated_time_to_regain_access": 0
        }
    ],
...
}

Códigos de erro

Quando o app chegar ao limite de volume do caso de uso da empresa, as solicitações subsequentes feitas por ele falharão, e a API responderá com um código de erro.

Mensagem do código SampleError

{   
"error": {      
    "message": "(#80001) There have been too many calls to this Page account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.",      
    "type": "OAuthException",      
    "code": 80001,      
    "fbtrace_id": "AmFGcW_3hwDB7qFbl_QdebZ"   
    }
}

Boas práticas

• Quando o limite tiver sido atingido, pare de fazer chamadas à API. Se você seguir fazendo chamadas, a contagem delas continuará aumentando. Com isso, levará ainda mais tempo para que as chamadas voltem a ser bem-sucedidas.
• Verifique o cabeçalho HTTP X-Business-Use-Case-Usage para verificar se a conta de anúncios está próxima do limite e quando você poderá voltar a fazer chamadas.
• Verifique o código de erro e o ponto de extremidade da API para confirmar o tipo de limitação.
• Mude para outras contas de anúncios e volte a esta conta mais tarde.
• É melhor criar um novo anúncio em vez de alterar os atuais.
• Divida as consultas de maneira uniforme entre dois intervalos de tempo para evitar o envio de tráfego em picos.
• Use filtros para limitar o tamanho da resposta de dados e evite chamadas que solicitem dados sobrepostos.

Perguntas frequentes

O que consideramos uma chamada de API?

Todas as chamadas contam para o limite de volume, não apenas solicitações individuais à API. Por exemplo, você pode fazer uma única solicitação à API e especificar vários números de identificação. Entretanto, cada um deles contará como uma chamada de API.

A tabela a seguir exemplifica isso.

Recomendamos que você especifique vários números de identificação em uma solicitação de API sempre que possível, pois isso melhora o desempenho das respostas.

Estou criando um extrator. Devo me preocupar com mais alguma coisa?

Se você estiver criando um serviço que extrai dados, leia nossos termos de extração.