O que é o limite de taxa da API do Pinterest, por app e por usuário

O que é o limite de taxa da API do Pinterest?

Dois tetos governam o limite de taxa da API do Pinterest e o menor é o que te trava: um limite universal que vale para todas as requisições e um limite por categoria que o Pinterest coloca por cima. A referência de rate limits fixa os números universais em "Trial access: 1000 requests per day for all API requests" e "Standard access: 100 requests per second per user per app for all API requests."

A unidade muda conforme o nível de acesso, e esse é o detalhe que a maioria das integrações erra. A página de níveis de acesso do Pinterest soletra: "Apps with Trial access are rate limited based on calls per day/per app", enquanto "Apps with Standard access are rate limited at a more granular level at calls per minute/per user/per app." Um app em Trial tem um único orçamento diário compartilhado, não importa quantas contas atenda. Um app em Standard ganha um orçamento por minuto novo para cada usuário conectado.

Todo endpoint pertence a exatamente uma categoria de rate limit, e a categoria é publicada na própria descrição OpenAPI do Pinterest como o campo x-ratelimit-category. O Pinterest ainda avisa na mesma página que "all rate limits are subject to change without notice."

Quais são os limites de taxa do Pinterest em cada categoria?

Doze categorias carregam números próprios. Os valores de Trial são requisições por dia por app e os de Standard são requisições por minuto por usuário por app, exceto onde a linha disser outra coisa.

Em qual categoria de limite de taxa entra publicar um Pin?

Publicar cai em org_write, o orçamento mais apertado que um agendador encosta: 300 chamadas por dia no Trial e 100 chamadas por minuto no Standard. A descrição OpenAPI publicada do Pinterest, versão 5.28.0 da Pinterest REST API, marca cada operação direto:

Pins de vídeo custam duas chamadas org_write em vez de uma. media/create registra o envio e devolve uma upload_url, o arquivo em si vai para essa URL e não para a API, e pins/create depois anexa a mídia pronta. Ler sai bem mais barato que escrever no acesso Standard, 1.000 por minuto contra 100, e as análises não saem mais baratas que nenhum dos dois, a 60 por minuto. Um painel que consulta análises Pin a Pin para 200 Pins vai bater em org_analytics muito antes de um publicador bater em org_write.

O teto diário do Trial é o que pega quem monta a primeira integração. Com 300 chamadas org_write por dia, um app em Trial cria por volta de 300 Pins de imagem ou 150 Pins de vídeo em 24 horas, divididos entre todas as contas conectadas a ele. Esse orçamento também explica boa parte dos motivos pelos quais um Pin não é publicado durante os testes.

Onde os próprios números do Pinterest se contradizem

O Pinterest publica números em duas páginas e em uma especificação, e eles não batem. Vale conhecer três lacunas antes de dimensionar uma fila.

O limite universal do Standard é 60 vezes o limite de categoria que fica abaixo dele. A página de rate limits diz que o acesso Standard recebe "100 requests per second per user per app for all API requests", o que dá 6.000 por minuto. A tabela de categorias da mesma página limita org_write a 100 por minuto. O número menor vence, e o próprio exemplo de cabeçalhos do Pinterest confirma que mais de uma janela é aplicada ao mesmo tempo:

< x-ratelimit-limit: 100, 100;w=1, 1000;w=60
< x-ratelimit-remaining: 99
< x-ratelimit-reset: 1

Isso se lê como 100 em uma janela de um segundo e 1.000 em uma janela de sessenta segundos, o que não é nem 6.000 nem 100.

O limite universal do Trial é maior que dois limites de categoria embaixo dele. O Trial é descrito como "1000 requests per day for all API requests", mas ads_write e org_write aparecem os dois com 300 por dia na tabela de categorias.

O endpoint de conversões contradiz a própria categoria. A página de rate limits coloca ads_conversions em 120.000 requisições por minuto por conta de anúncios por app no Standard. A descrição de POST /v5/ad_accounts/{ad_account_id}/events, que carrega x-ratelimit-category: ads_conversions, diz na especificação publicada do Pinterest: "This endpoint has a rate limit of 5,000 calls per minute per ad account." Isso é um fator de 24 entre duas fontes do Pinterest para o mesmo endpoint.

Construa contra o número menor de cada par. O Pinterest não diz qual página tem precedência.

Como é uma resposta 429 do Pinterest?

Todo endpoint da especificação documenta um 429, descrito como "the user has sent too many requests in a given amount of time and is being rate limited." O corpo é o objeto de erro genérico do Pinterest, um documento JSON com exatamente dois campos obrigatórios:

{
  "code": 2,
  "message": "AdAccount not found."
}

Esse exemplo é o que o Pinterest entrega na especificação para o esquema de erro compartilhado, não um exemplo de rate limit. A referência de códigos de erro do Pinterest lista códigos para listas de clientes, públicos e feeds de compras, e não publica nenhum code numérico para um 429. A especificação não documenta cabeçalho Retry-After nem cabeçalhos de resposta x-ratelimit-* em endpoint nenhum, mesmo com a página de rate limits mostrando esses cabeçalhos em um exemplo de cURL. Trate os cabeçalhos como reais e o código numérico como não documentado, e amarre sua lógica de retentativa ao status HTTP em vez do corpo.

Como ficar abaixo do limite de taxa da API do Pinterest?

Leia os contadores em vez de chutar. O método documentado pelo Pinterest é rodar as requisições em modo verboso e inspecionar a resposta, como em curl -v --location --request GET 'https://api.pinterest.com/v5/pins' --header 'Authorization: Bearer <token>', e então acompanhar x-ratelimit-remaining contra x-ratelimit-limit por categoria e não por app.

Quatro hábitos mantêm uma integração dentro do orçamento:

• Faça o orçamento por categoria, não por integração. Um publicador, um coletor de análises e uma sincronização de catálogo puxam de org_write, org_analytics e catalogs_write separadamente, então um deles saturar não freia os outros.
• Espalhe as escritas do nível Standard ao longo do minuto. A 100 chamadas org_write por minuto por usuário, uma rajada de 200 Pins na fila para uma conta precisa de dois minutos de cadência, a mesma aritmética que governa o orçamento de pontos do Bluesky e os 100 posts por 24 horas do Instagram.
• Saia do Trial antes do lançamento. O Trial limita org_write a 300 por dia para o app inteiro e, segundo a página de níveis de acesso, Pins e pastas criados no Trial "are only visible to their creator as Sandbox entities", então nada do que você publica em teste é público de qualquer forma.
• Peça mais quando o padrão tiver ficado pequeno. O caminho documentado pelo Pinterest é abrir um chamado com o time de suporte, que é também como você libera uma vaga diante do limite de cinco apps que o FAQ menciona.

Se você marca o ritmo de uma fila na mão em vez de por um cliente de API, a mesma aritmética por minuto vale para agendar posts do Pinterest em massa.

Perguntas frequentes

Quantos Pins posso criar por dia com a API do Pinterest?

No acesso Trial, cerca de 300, porque pins/create cai em org_write e o Trial limita essa categoria a 300 requisições por dia por app. No acesso Standard não há teto diário publicado para org_write, só 100 requisições por minuto por usuário por app, o que dá 144.000 por dia se você sustentasse esse ritmo.

O limite de taxa da API do Pinterest é por app ou por usuário?

Os dois, conforme o nível. O acesso Trial é medido por dia por app, então todas as contas conectadas dividem um orçamento. O acesso Standard é medido por minuto por usuário por app, então cada conta conectada ganha o seu.

Qual código HTTP o Pinterest retorna quando aplica limite de taxa?

429. A descrição OpenAPI do Pinterest o define em todo endpoint com a descrição "the user has sent too many requests in a given amount of time and is being rate limited", e o corpo da resposta é o objeto de erro genérico com code e message.

Quais cabeçalhos mostram minha cota restante da API do Pinterest?

x-ratelimit-limit, x-ratelimit-remaining e x-ratelimit-reset. A página de rate limits mostra os três em um exemplo verboso de cURL, com x-ratelimit-limit carregando mais de uma janela, como em 100, 100;w=1, 1000;w=60.

O Pinterest publica um valor Retry-After para respostas 429?

Não. Nem a página de rate limits nem a descrição OpenAPI publicada definem Retry-After em endpoint nenhum. O único sinal de tempo que o Pinterest documenta é x-ratelimit-reset, mostrado com valor 1 no exemplo dele mesmo.

Como consigo um limite de taxa maior na API do Pinterest?

Suba o app para o acesso Standard e depois abra um chamado de suporte. A página de níveis de acesso conduz a mudança pelo My apps e exige uma gravação em vídeo do fluxo de OAuth, e a página de rate limits manda quem quiser outra mudança abrir um chamado com o suporte do Pinterest.

Existe um limite para quantos apps posso registrar no Pinterest?

O próprio FAQ do Pinterest menciona um limite de cinco apps por conta de desenvolvedor. O mesmo caminho de ticket de suporte usado para pedir um limite de taxa maior é o que libera uma vaga depois que esse limite é ultrapassado.

Pins de vídeo consomem mais do limite de taxa do que Pins de imagem?

Um Pin de vídeo custa duas chamadas org_write em vez de uma, porque media/create registra o upload antes de pins/create anexar o arquivo finalizado. Essa duplicação faz o orçamento de 300 chamadas org_write no Trial cobrir cerca de 150 Pins de vídeo por dia, a metade do que cobre só com Pins de imagem.

Pins criados com acesso Trial ficam visíveis para outras pessoas?

Pins e boards criados enquanto um app está em acesso Trial são entidades Sandbox, visíveis só para quem os criou, segundo a página de níveis de acesso do Pinterest. Testar contra o teto de 300 chamadas org_write por dia não custa exposição pública, já que nada publicado antes de migrar para o Standard é público mesmo assim.

Quanto mais barato é ler do que escrever no acesso Standard do Pinterest?

org_read roda a 1.000 solicitações por minuto por usuário por app no acesso Standard, dez vezes as 100 por minuto que org_write permite. Analytics fica abaixo dos dois, com 60 por minuto. Essa diferença explica por que um painel que consulta analytics de 200 Pins bate no teto antes de um publicador bater no de org_write.