Limites de solicitações

Um limite de solicitações restringe quantas chamadas você pode enviar em um intervalo curto. Quando você o ultrapassa, a API responde 429 (“solicitações demais”), em vez de executar o trabalho, e informa quanto tempo esperar. É uma proteção contra scripts descontrolados, não uma cota de geração.

Visão geral dos limites

Dois controles por conta: leitura e escrita

Toda a API — os caminhos /api/v1/* e os endpoints compatíveis /v1/* e /v1beta/* — tem limites por conta, não por chave. Se o limite fosse por chave, bastaria criar mais chaves para contorná-lo.

Leituras e escritas são contabilizadas em dois controles separados, com a mesma capacidade. O limite padrão de proteção é de 1.000 solicitações por 10 segundos em cada um: cerca de 100 RPS sustentadas (solicitações por segundo), com pico de 1.000. Trata-se de uma proteção geral contra abuso e clientes descontrolados, não de uma cota baixa para o tráfego normal de geração paga.

O controle usa um token bucket, e não um contador de janela fixa: capacidade de 1.000, reposta ao longo de 10 segundos, cerca de 100 tokens por segundo. Cada solicitação consome um token; os tokens são repostos continuamente. Ao contrário de uma janela fixa, o token bucket suaviza a reposição nas transições entre intervalos.

upload-url tem uma proteção própria de 1.000 solicitações por 10 segundos, além do controle de escrita acima. Ela protege separadamente a autorização de gravação no armazenamento de objetos; uploads normais não devem se aproximar desse limite.

usage tem uma proteção adicional bem mais restrita: 30 solicitações por minuto, além do controle de leitura acima. Essa chamada agrega tarefas históricas, portanto custa muito mais que uma leitura comum e precisa de mais proteção que apenas o limite geral. Use-a para conciliação, não para consultas contínuas. Esse controle também nunca libera chamadas quando a decisão de limite está indisponível: nesse caso, ele sempre retorna 429, enquanto outros controles podem estar configurados para liberar o tráfego.

URLs de upload ainda não usadas

Separadamente, uma conta pode manter no máximo 128 URLs de upload ainda não usadas, ou um total de 1 GiB de tamanho declarado dos arquivos. Solicitar outra retorna 429, com Too many pending uploads; finish existing uploads before requesting more, e sem Retry-After.

Esperar não resolve esse caso; não deixe um laço genérico de tentativas repeti-lo indefinidamente. Envie e confirme os arquivos cujas URLs você já solicitou, ou deixe essas URLs expirarem, o que leva cerca de 20 minutos, e o espaço será liberado imediatamente. Isso costuma acontecer quando um script solicita URLs de upload em lote e nunca as usa. Veja Mídia.

Todos os controles

Os limites são aplicados por área de acesso, de modo que todos os endpoints de uma mesma área compartilham uma cadeia de middleware. Como consumidor da API, você pode atingir os cinco primeiros:

Esses números são valores padrão que podemos alterar sem uma nova versão. Sua capacidade atual sempre aparece no cabeçalho X-RateLimit-Limit e na Visão geral do console. Confie no cabeçalho e não fixe os valores padrão no código do cliente.

Cabeçalhos de resposta

Uma resposta normal de uma conta com a capacidade padrão contém:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997

Como é a resposta ao atingir um limite

{
  "code": 429,
  "msg": "Too many requests. Retry in a moment",
  "request_id": "req_…"
}

Status HTTP 429, com Retry-After.

Como tratar

Leia Retry-After. Não insista em intervalos fixos. Os exemplos param após cinco tentativas, o que também evita repetir para sempre o 429 de uploads pendentes explicado acima.

async function callRespectingLimits(url, init) {
  for (let i = 0; i < 5; i++) {
    const res = await fetch(url, init);

    if (res.status !== 429) return res;

    // The server already told you how long to wait; don't guess
    const wait = Number(res.headers.get('retry-after') ?? 1);
    await new Promise((r) => setTimeout(r, wait * 1000));
  }
  throw new Error('persistently rate-limited');
}

import time, requests


def call_respecting_limits(method: str, url: str, **kwargs) -> requests.Response:
    for _ in range(5):
        res = requests.request(method, url, **kwargs)

        if res.status_code != 429:
            return res

        # The server already told you how long to wait; don't guess
        time.sleep(float(res.headers.get("retry-after", 1)))

    raise RuntimeError("persistently rate-limited")

Concorrência é outra questão

O que realmente limita as tarefas em andamento, sem relação com o limite de solicitações:

• Saldo disponível: cada tarefa em andamento reserva saldo. Quando o saldo acaba, novas tarefas recebem 40201.
• Limites de gastos: limites diário, mensal e total da chave, limites diário e mensal da equipe para chaves que pertencem a uma equipe e limite diário da plataforma. Atingir qualquer um deles retorna 40202. Veja Limites de gastos.
• Capacidade de execução: quando um modelo não consegue executar de forma alguma, você recebe 50301.

Por isso, para executar mais tarefas ao mesmo tempo, normalmente você precisa adicionar saldo ou elevar um limite de gastos, e não aumentar o limite de solicitações.

Como pedir mais capacidade

Sua capacidade atual aparece na Visão geral do console. Para pedir um aumento, abra uma conversa em Suporte, no assunto Integração de API, e descreva seu tráfego: pico de solicitações por segundo, se você usa lotes e qual o tamanho máximo de um lote. Isso agiliza bastante a análise.

Enquanto isso, mantenha a concorrência do cliente limitada e respeite Retry-After. Defina o limite de concorrência conforme a carga de trabalho, o tempo de geração e o saldo disponível, em vez de reduzi-lo artificialmente para caber no limite padrão de solicitações.

Quando o próprio controle de limites está indisponível

O controle de limites depende de um contador externo. Se ele falhar, a configuração determina a ação: permitir, mantendo o atendimento, ou recusar, protegendo a capacidade. Recusar é o padrão: “não conseguimos ler a configuração” nunca deve resultar em “não há limite”.

Quando a configuração determina a recusa, você recebe 429 com Retry-After: 1, não 500. Isso é intencional: 500 indica uma falha do serviço, e a maioria dos SDKs de cliente o repete imediatamente, aumentando a carga durante um incidente. 429 com Retry-After pede que o cliente aguarde e tente depois, que é o comportamento necessário.

Portanto, não interprete 429 como prova de que você estava enviando chamadas rápido demais. Respeitar Retry-After é a resposta correta em qualquer um dos casos.