Cotas e limite de requisições

Duas coisas independentes limitam o que você pode fazer: quantas buscas o seu plano permite por dia e com que velocidade as requisições podem chegar. As duas são informadas em todas as respostas, para que um cliente possa se regular sem precisar provocar um erro para descobrir onde estão os limites.

Limite de requisições: dez por minuto

O limite é por conta e é compartilhado pela API e pelo servidor MCP: dez chamadas por minuto, venham de onde vierem. Uma décima primeira requisição dentro dessa janela volta imediatamente com 429 too_many_requests e um cabeçalho Retry-After com os segundos que faltam até uma vaga ser liberada. O mesmo número vem no corpo como error.retry_after.

HTTP/2 429
Retry-After: 18

{ "error": { "code": "too_many_requests",
             "message": "At most 10 requests per minute.",
             "retry_after": 18 } }

Espere Retry-After segundos e repita a requisição. Nada foi consumido, e nenhuma cota foi gasta.

A API nunca mantém uma conexão aberta para deixar você mais lento. As URLs de exportação antigas fazem isso: esperam um segundo de cada vez, por até meio minuto, antes de recusar, e esse é um dos motivos pelos quais a API existe.

Cota diária

O seu plano permite um número de buscas por dia e um número de requisições com trechos por dia, contados separadamente. Os dois são zerados à meia-noite UTC seguinte, e não 24 horas depois do uso.

• Uma busca consome uma unidade da cota de buscas.
• Uma busca com snippets=1 consome, em vez disso, uma unidade da cota de trechos.
• /v1/account não consome nada.

Quando uma cota acaba, a requisição é recusada com 429 quota_exceeded ou 429 snippet_quota_exceeded, informando o limite, quanto já foi usado e quanto tempo falta para zerar. Ficar sem cota de trechos não impede as buscas comuns.

Profundidade dos resultados

O plano também define até que posição do ranking os resultados são exibidos: disclosed_positions, em /v1/account. As linhas além desse ponto são omitidas, e não deixadas em branco, e, quando isso acontece, truncated é true no corpo e X-Truncated: true nos cabeçalhos.

Essa é a diferença mais importante entre a API e o site. Um navegador cuja cota acabou volta discretamente à profundidade do plano gratuito e mostra menos, o que não é problema para uma pessoa olhando uma página. Um script não consegue perceber isso, então a API recusa em vez de encurtar.

Como ler o estado atual

Toda resposta autenticada traz cinco cabeçalhos:

Os resultados trazem mais três:

Estatísticas de uso

/v1/account mostra o quadro completo em uma única chamada e não consome nada:

curl -H "Authorization: Bearer $KEY" https://api.publicwww.com/v1/account

{
  "plan": "enterprise",
  "plan_until": 1819461840,
  "full_access": true,
  "quota": {
    "searches": { "limit": 300, "used": 12, "resets_at": 1787961600 },
    "snippets": { "limit": 100, "used": 3,  "resets_at": 1787961600 }
  },
  "limits": {
    "disclosed_positions": 4294967295,
    "disclosed_positions_snippets": 4294967295,
    "max_per_page": 1000000,
    "max_per_page_snippets": 10000
  }
}

O antigo https://publicwww.com/profile/api_status.xml?key=... informa os mesmos contadores em XML e continua funcionando. Ele faz parte das URLs antigas; código novo deve usar /v1/account, que também informa os limites, e não só as contagens.