O limite de taxa da Instagram API é 4800 vezes as suas impressões

Qual é o limite de taxa da Instagram API?

Uma fórmula define o limite de taxa da Instagram API, e a Meta a imprime como uma linha única tanto na referência de rate limiting da Graph API quanto na visão geral da Instagram Platform: Calls within 24 hours = 4800 * Number of Impressions.

A frase em volta importa tanto quanto a fórmula. A Meta escreve: "Calls to the Instagram Platform endpoints, excluding messaging, are counted against the calling app's call count. An app's call count is unique for each app and app user pair, and is the number of calls the app has made in a rolling 24 hour window."

Três restrições se escondem nessa frase. A contagem pertence ao app, não à conta. Ela tem escopo de um app e um usuário do app juntos, então um cliente movimentado não consegue matar de fome um cliente quieto. E a janela é móvel, então nada zera à meia-noite. As chamadas envelhecem uma a uma, 24 horas depois de cada uma ter sido feita.

A Instagram Platform fica dentro da categoria Business Use Case da Meta, e não da categoria mais antiga de Platform Rate Limits. Requisições da Marketing API e do Instagram estão sujeitas aos limites de Business Use Case; requisições comuns da Graph API estão sujeitas aos limites de Platform. Onde os dois poderiam valer, a Meta resolve em uma linha: "If both Platform and Business Use Case rate limits can be applied to a request, BUC rate limits will be applied."

A que o multiplicador 4800 se aplica?

A impressões, e a Meta define a palavra de forma estreita: "The Number of Impressions is the number of times any content from the app user's Instagram professional account has entered a person's screen within the last 24 hours."

Leia isso como contagem de telas, não contagem de seguidores, nem de posts, nem de alcance. Conta aparições, então uma pessoa rolando por quatro dos seus posts contribui com quatro. Cobre "any content" da conta, então posts antigos que ainda puxam tráfego contam igual aos desta manhã. E é medida sobre as mesmas 24 horas móveis das chamadas que financia, o que faz a franquia se mover continuamente em vez de em degraus.

Isso produz um orçamento que escala com atenção. Uma conta cujos posts entraram em telas 50.000 vezes no último dia financia 240.000.000 de chamadas, um número que nenhum fluxo de publicação chega perto. A fórmula só morde na ponta de baixo, porque a Meta não publica piso nenhum: 4800 multiplicado por zero impressões dá zero chamadas, e em nenhum ponto da referência de rate limiting a Meta declara franquia mínima para uma conta que ninguém viu.

A mesma estrutura aparece em outros pontos da tabela da Meta. Chamadas da Pages API feitas com token de Página ou de usuário de sistema usam Calls within 24 hours = 4800 * Number of Engaged Users, e LeadGen usa Calls within 24 hours = 4800 * Leads Generated. O multiplicador 4800 é o número da casa da Meta para um business use case de 24 horas; só muda a coisa que está sendo multiplicada.

Como se lê o cabeçalho X-Business-Use-Case-Usage?

A Meta devolve o uso em um cabeçalho de resposta, e não no corpo: "All API responses made by your app that are rate limited using the BUC logic include an X-Business-Use-Case-Usage HTTP header with a JSON-formatted string that describes current application rate limit usage. This header can return up to 32 objects in one call."

O valor do cabeçalho é um objeto JSON com chave por ID de negócio, e cada entrada carrega estes campos.

Campo	O que a Meta diz que ele guarda
business-id	O ID do negócio associado ao token que faz as chamadas de API
call_count	Um número inteiro que expressa a porcentagem das chamadas permitidas feitas pelo seu app
total_cputime	Um número inteiro que expressa a porcentagem do tempo de CPU alocado para processar consultas
total_time	Um número inteiro que expressa a porcentagem do tempo total alocado para processar consultas
estimated_time_to_regain_access	Tempo, em minutos, até as chamadas deixarem de ser limitadas
type	Tipo de limite de taxa aplicado, um entre ads_insights, ads_management, custom_audience, instagram, leadgen, messenger ou pages

Para trabalho com Instagram, o campo a casar é type, e o valor a casar é instagram. Um app que também encosta em Pages ou Ads recebe vários objetos no mesmo cabeçalho, e ler o objeto errado te conta sobre o orçamento errado.

Cada um dos três números de uso é porcentagem, não contagem. call_count em 62 significa que 62 por cento da franquia foi gasta, e a Meta nunca te diz o denominador, porque o denominador é aquela cifra de impressões recalculada continuamente. Nenhum endpoint devolve o seu teto atual de chamadas como inteiro.

O cabeçalho também não aparece em toda resposta. A Meta escreve que as estatísticas de uso em tempo real vêm "included with most API responses once enough calls have been made to an endpoint." Trate um cabeçalho ausente como ausência de informação, não como uso zero.

Por que o cabeçalho diz uma hora quando a fórmula diz 24 horas?

Porque as duas páginas da Meta discordam, e a discordância está viva no mesmo documento. A seção do Instagram declara uma "rolling 24 hour window." A tabela do cabeçalho, algumas telas abaixo, define call_count como "A whole number expressing the percentage of allowed calls made by your app over a rolling one hour period."

As duas frases descrevem o mesmo campo, no mesmo cabeçalho, para a mesma API. Uma delas está errada para o Instagram. A redação de uma hora bate com a seção de Platform Rate Limits mais acima na página, onde as chamadas em nível de app são mesmo medidas por hora, o que é a origem mais provável do descompasso.

Nada na documentação resolve isso, então planeje para a janela mais longa. Se você supõe que o contador zera em uma hora e ele zera em 24, você tenta de novo contra uma parede. Se você supõe 24 e ele zera em uma, você esperou mais do que precisava. Só um desses dois erros quebra um calendário de publicação.

Uma segunda lacuna publicada está nas tabelas de erro. A lista de erros de Business Use Case da Meta nomeia o error code 80002 para o tipo Instagram, sem subcódigo. A referência de códigos de erro da Instagram Platform, a página que você de fato leria enquanto depura uma publicação, não lista 80002 em lugar nenhum. Mapeie por conta própria.

O que acontece quando call_count chega a 100?

As requisições falham com um código de erro dedicado. A Meta escreve: "When your app reaches its Business Use Case rate limit, subsequent requests made by your app will fail and the API will respond with an error code." Para o tipo Instagram, esse código é 80002.

Tempo de CPU e tempo de relógio limitam separadamente do volume de chamadas. A Meta repete as mesmas duas linhas sob cada business use case: "When total_cputime reaches 100, calls may be throttled" e "When total_time reaches 100, calls may be throttled." Qualquer um dos três chegando a 100 já basta. Um punhado de consultas pesadas consegue esgotar o total_cputime enquanto o call_count ainda está na casa de um dígito.

Uma vez limitado, estimated_time_to_regain_access carrega a espera em minutos, e a instrução que vem em seguida é a importante: "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."

Tentar de novo alonga o bloqueio. Isso é incomum o bastante para merecer projeto próprio, porque um backoff exponencial padrão ainda manda requisições, e cada uma delas estende a punição. O comportamento correto no 80002 é estacionar a fila até o cabeçalho dizer outra coisa. A mesma disciplina compensa na cota diária de publicação, que é um teto separado com erro próprio.

O resto do conselho da Meta é sobre espaçamento, não volume: "Spread out queries evenly to avoid traffic spikes" e "Use filters to limit the data response size and avoid calls that request overlapping data." Existe também uma regra de contagem que pega quem agrupa IDs. A Meta afirma que "each ID counts as one API call", e demonstra: três requisições separadas de um ID contam como três chamadas, e uma requisição com ids=4,5,6 também conta como três.

Duas respostas ao erro 80002

Parar a fila

• call_count deixa de subir
• estimated_time_to_regain_access faz a contagem regressiva
• as chamadas voltam a funcionar quando a espera termina

Continuar tentando

• cada nova tentativa aumenta ainda mais o call_count
• estimated_time_to_regain_access cresce
• a espera até as chamadas voltarem a funcionar fica mais longa

Quais endpoints do Instagram ficam fora desse limite?

Duas famílias, e a Meta as nomeia explicitamente.

Superfície	Limite que se aplica
Publicação, mídia, insights, comentários	4800 * Number of Impressions por 24 horas
Business Discovery, Hashtag Search	Platform Rate Limits, não Business Use Case
Conversations API	2 chamadas por segundo por conta profissional
Send API, texto e links	100 chamadas por segundo por conta profissional
Send API, áudio ou vídeo	10 chamadas por segundo por conta profissional
Private Replies, comentários ao vivo	100 chamadas por segundo por conta profissional
Private Replies, posts e reels	750 chamadas por hora por conta profissional

Mensageria é recortada por completo da fórmula de impressões e roda em tetos por segundo e por hora. Business Discovery e Hashtag Search caem de volta nos Platform Rate Limits, onde a fórmula em nível de app é Calls within one hour = 200 * Number of Users.

O limite de taxa também não é a cota de publicação. São sistemas separados com erros separados, e confundi-los desperdiça tempo de depuração: uma publicação bloqueada por volume devolve 80002, enquanto uma publicação bloqueada pela cota de publicação de conteúdo devolve código 9, subcódigo 2207042. Outras redes se dividem do mesmo jeito, sejam os tetos de requisição que o Bluesky publica por endpoint ou o orçamento diário de unidades que o YouTube mede e deixa você pedir para ampliar.

Perguntas frequentes

Qual é a fórmula do limite de taxa da Instagram API?

Calls within 24 hours = 4800 * Number of Impressions. A Meta a publica na referência de rate limiting da Graph API e a repete na visão geral da Instagram Platform.

O que conta como impressão no limite de taxa do Instagram?

A Meta define como "the number of times any content from the app user's Instagram professional account has entered a person's screen within the last 24 hours." Conta aparições de qualquer conteúdo, não seguidores e não posts.

Qual código de erro significa que o limite de taxa da Instagram API foi atingido?

O código de erro 80002. A Meta o lista no tipo de business use case do Instagram sem subcódigo, e não o repete na referência de códigos de erro da Instagram Platform.

Como verificar o uso atual do limite de taxa da Instagram API?

Leia o cabeçalho de resposta X-Business-Use-Case-Usage, encontre o objeto em que type é instagram e confira call_count, total_cputime e total_time. Os três são porcentagens da franquia.

Tentar de novo depois de um erro de limite de taxa piora a situação?

Sim. A Meta escreve que continuar a fazer chamadas "will continue to increase your call count, which will increase the time before calls will be successful again." Pare a fila e leia estimated_time_to_regain_access.

Os endpoints de mensageria do Instagram são cobertos pela fórmula 4800?

Não. A Meta exclui mensageria da fórmula de impressões e publica tetos por segundo e por hora para as APIs Conversations, Send e Private Replies.

O limite de taxa da Instagram API reinicia num horário fixo todos os dias?

Ele não reinicia à meia-noite nem em nenhum outro horário fixo. A Meta conta as chamadas numa janela móvel de 24 horas, então cada chamada sai da contagem exatamente 24 horas depois de ter sido feita. O saldo disponível se move de forma contínua em vez de voltar a zero segundo um horário.

A contagem de chamadas da Instagram API é compartilhada entre todos os apps conectados à minha conta?

Cada app mantém a própria contagem. A Meta associa o contador de chamadas a um único par de app e usuário do app, então um app muito ativo não consegue esgotar o saldo que pertence a outro app que acessa a mesma conta.

Qual é a diferença entre o limite de taxa da Instagram API e a cota diária de publicação?

São sistemas separados com erros separados. O limite de taxa descrito aqui bloqueia com o código de erro 80002 quando call_count, total_cputime ou total_time chega a 100. A cota diária de publicação é um teto diferente e falha com o código 9, subcódigo 2207042, então um bloqueio de um tipo nunca explica um bloqueio do outro.

As chamadas para Business Discovery e Hashtag Search contam na fórmula 4800?

Elas ficam fora dela. Os dois endpoints funcionam sob a categoria mais antiga da Meta, Platform Rate Limits, em vez de Business Use Case, onde a fórmula aplicada é 200 vezes o número de usuários por hora, em vez de 4800 vezes as impressões.