Limites de taxa

Limites de taxa são restrições que nossa API impõe ao número de vezes que um usuário ou cliente pode acessar nossos serviços em um período específico.

Por que temos limites de taxa?

Limites de taxa são uma prática comum em APIs e são adotados por alguns motivos:

• Eles ajudam a proteger contra o uso abusivo ou indevido da API. Por exemplo, um agente mal-intencionado poderia inundar a API com requisições para tentar sobrecarregá-la ou causar interrupções no serviço. Ao definir limites de taxa, a OpenAI pode impedir esse tipo de atividade.
• Os limites de taxa ajudam a garantir que todos tenham acesso justo à API. Se uma pessoa ou organização fizer um número excessivo de requisições, isso poderá deixar a API lenta para todos os demais. Ao limitar o número de requisições que um único usuário pode fazer, a OpenAI garante que o maior número possível de pessoas tenha a oportunidade de usar a API sem lentidão.
• Os limites de taxa podem ajudar a OpenAI a gerenciar a carga total em sua infraestrutura. Um aumento drástico nas requisições à API pode sobrecarregar os servidores e causar problemas de desempenho. Ao definir limites de taxa, a OpenAI pode ajudar a manter uma experiência fluida e consistente para todos os usuários.

Como esses limites de taxa funcionam?

Os limites de taxa usam métricas como RPM (requisições por minuto), RPD (requisições por dia), TPM (tokens por minuto), TPD (tokens por dia), IPM (imagens por minuto) e minutos de áudio por minuto para alguns modelos de áudio em streaming. O limite atingido será o da métrica que alcançar seu valor máximo primeiro. Por exemplo, você poderia enviar 20 requisições com apenas 100 tokens ao endpoint ChatCompletions e atingir seu limite (se seu RPM fosse 20), mesmo sem enviar 150 mil tokens (se seu limite de TPM fosse 150 mil) nessas 20 requisições.

Os limites de fila da API de processamento em lote são calculados com base no número total de tokens de entrada na fila para um determinado modelo. Os tokens de tarefas de processamento em lote pendentes são contabilizados no seu limite de fila. Quando uma tarefa de processamento em lote é concluída, seus tokens deixam de ser contabilizados no limite desse modelo.

Outros pontos importantes:

• Os limites de taxa são definidos no nível da organização e no nível do projeto, não no nível do usuário.
• Os limites de taxa variam conforme o modelo utilizado.
• Para modelos de contexto longo, como o GPT-5.5, há um limite de taxa separado para requisições de contexto longo. Você pode consultar esses limites no console do desenvolvedor.
• A OpenAI define um limite de uso mensal aprovado para cada organização. Esse limite é separado dos limites de gastos que você pode configurar para uma organização ou projeto.
• Algumas famílias de modelos têm limites de taxa compartilhados. Todos os modelos listados em um "limite compartilhado" na página de limites da sua organização compartilham um limite de taxa entre si. Por exemplo, se o TPM compartilhado listado for de 3,5 milhões, todas as chamadas a qualquer modelo nessa lista de "limite compartilhado" serão contabilizadas nesses 3,5 milhões.
• A ingestão em armazenamentos vetoriais também tem limites de taxa por ID de armazenamento vetorial. /vector_stores/{vector_store_id}/files e /vector_stores/{vector_store_id}/file_batches compartilham um limite de 300 requisições por minuto para cada armazenamento vetorial. Para ingestões maiores, prefira /vector_stores/{vector_store_id}/file_batches.

Níveis de uso

Você pode consultar os limites de taxa e de uso da sua organização na seção limites das configurações da sua conta. Conforme seus gastos com nossa API aumentam, você passa automaticamente para o próximo nível de uso. Isso geralmente resulta em um aumento dos limites de taxa para a maioria dos modelos.

Para consultar um resumo geral dos limites de taxa por modelo, acesse a página de modelos.

Limites de taxa nos cabeçalhos

Além de consultar seu limite de taxa na página da sua conta, você também pode encontrar informações importantes sobre seus limites de taxa, como requisições e tokens restantes e outros metadados, nos cabeçalhos da resposta HTTP.

As respostas podem incluir os seguintes campos de cabeçalho:

Os cabeçalhos de tokens do projeto podem estar presentes quando há um limite de tokens aplicado ao projeto. Retry-After pode estar presente em respostas 429 causadas por um limite de taxa temporário e em respostas 503 causadas por uma sobrecarga temporária do modelo. Isso não significa que erros de cota, de faturamento ou outros erros que exigem uma ação do usuário possam ser resolvidos com novas tentativas.

Limites de taxa de ajuste fino

Os limites de taxa de ajuste fino da sua organização também podem ser consultados no painel e obtidos pela API:

curl https://api.openai.com/v1/fine_tuning/model_limits \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Mitigação de erros

Lide com aumentos rápidos de tráfego e sobrecarga do modelo

A API pode retornar slow_down quando sua taxa de requisições aumenta rápido demais, ou server_is_overloaded quando o modelo solicitado está temporariamente sobrecarregado. Verifique o status HTTP e error.code para distinguir essas situações:

Se Retry-After não estiver presente, aumente o intervalo entre as novas tentativas e acrescente um pequeno tempo de espera aleatório.

Um erro slow_down pode ocorrer mesmo quando seu tráfego está dentro dos limites de requisições por minuto e de tokens por minuto. Ele indica a rapidez com que o tráfego aumentou, e não se você esgotou esses limites.

Como regra geral, quando seu tráfego atingir 1 milhão de tokens de entrada por minuto (TPM), aumente-o em no máximo 50% a cada 15 minutos. O ponto exato em que o limite de velocidade de aumento do tráfego se aplica pode variar conforme o modelo e as condições de tráfego.

Clientes empresariais cujo tráfego com pagamento conforme o uso atinge regularmente os limites de velocidade de aumento do tráfego podem considerar o Nível de escala para obter uma capacidade mais previsível nos modelos elegíveis. Para o GPT-5.6 e modelos posteriores, consulte o Nível reservado. Os níveis de capacidade não mudam a forma de lidar com uma resposta slow_down: respeite Retry-After quando estiver presente, reduza o tráfego e aumente-o gradualmente.

Atualize os tratamentos de erro existentes

Se sua aplicação tratava as respostas anteriores de limitação de tráfego e sobrecarga, verifique tanto o status HTTP quanto error.code:

• Nos endpoints que antes retornavam 503 com o código slow_down para ambas as situações, aumentos rápidos de tráfego agora retornam 429 com slow_down. A sobrecarga do modelo continua retornando 503, mas usa server_is_overloaded.
• As requisições de vídeo rejeitadas antes da criação de um job retornavam anteriormente 429 com o tipo invalid_request_error e o código rate_limit_exceeded nessas situações. Aumentos rápidos de tráfego agora retornam 429 com rate_limit_error e slow_down; a sobrecarga do modelo retorna 503 com service_unavailable_error e server_is_overloaded. Os erros informados no status de um job de vídeo são um caso à parte.

Trate tanto 429 quanto 503 no tratamento de erros do SDK. Por exemplo, Python, TypeScript e Ruby usam RateLimitError para 429 e InternalServerError para 503; Java usa RateLimitException e InternalServerException. Mantenha o suporte aos códigos de resposta anteriores enquanto sua aplicação ainda puder recebê-los. Outros erros podem usar os mesmos status HTTP, portanto, examine o corpo do erro antes de escolher uma ação de recuperação.

Para requisições com streaming, essas respostas de erro HTTP se aplicam antes do início do streaming. Um erro ocorrido após o início do streaming pode chegar como um evento do fluxo; não repita automaticamente uma requisição depois de consumir dados de saída.

Que medidas posso tomar para mitigar isso?

O OpenAI Cookbook tem um notebook Python que explica como evitar erros de limite de taxa, além de um exemplo de script Python para se manter dentro dos limites de taxa ao processar requisições à API em lote.

Você também deve ter cuidado ao oferecer acesso programático, recursos de processamento em massa e publicação automatizada em redes sociais. Considere habilitá-los apenas para clientes de confiança.

Para se proteger contra o uso indevido automatizado e em grande volume, defina um limite de uso por usuário para um período específico (diário, semanal ou mensal). Considere implementar um teto que não possa ser ultrapassado ou um processo de revisão manual para usuários que excedam o limite.

Novas tentativas com recuo exponencial

Quando uma requisição excede um limite de taxa temporário, a API retorna um erro 429. A resposta pode incluir um cabeçalho Retry-After que informa quantos segundos esperar antes de tentar novamente. Trate esse valor como um mínimo: espere pelo menos esse tempo e acrescente um pequeno tempo de espera aleatório para que vários clientes não tentem novamente ao mesmo tempo.

Cada OpenAI SDK oficial faz novas tentativas automaticamente para respostas 429 e 503 elegíveis, conforme suas configurações de novas tentativas. O tratamento de Retry-After, especialmente de tempos de espera longos, varia conforme a versão e a configuração do SDK. Verifique o comportamento de novas tentativas da versão instalada, em vez de presumir que qualquer tempo de espera indicado pelo servidor seja aceito.

Se um tempo de espera válido indicado pelo servidor exceder o tempo máximo de espera entre tentativas aceito ou configurado, interrompa as tentativas e adie a requisição, em vez de tentar novamente antes do prazo. Um SDK pode retornar o erro HTTP original quando não aceita um tempo de espera acima do seu limite. Continue tratando separadamente os erros de cancelamento e de tempo limite: uma requisição cancelada ou um prazo expirado pode interromper as tentativas sem retornar esse erro HTTP. Um tempo limite para cada tentativa não é necessariamente um prazo para a operação inteira.

Se estiver usando seu próprio cliente HTTP, respeite Retry-After quando o cabeçalho estiver presente e contiver um valor válido. Se estiver ausente ou for inválido, use recuo exponencial com variação aleatória. Limite tanto o número de tentativas quanto o tempo total gasto nelas. Se você gerencia as novas tentativas na sua aplicação, desative as novas tentativas do SDK ou contabilize-as nesses limites para que laços de novas tentativas aninhados não multipliquem as requisições. Não repita requisições com erros de cota, de faturamento ou outros erros que exijam uma ação sua.

O recuo exponencial consiste em esperar brevemente após uma requisição malsucedida e aumentar o tempo de espera a cada nova tentativa que falhar. Isso continua até que a requisição seja bem-sucedida ou atinja o limite configurado de novas tentativas.

Essa abordagem tem vários benefícios:

• As novas tentativas automáticas permitem se recuperar de erros de limite de taxa sem travamentos nem perda de dados
• O recuo exponencial permite realizar as primeiras novas tentativas rapidamente, com a vantagem de usar intervalos maiores caso elas falhem
• Adicionar uma variação aleatória ao tempo de espera ajuda a evitar que todas as novas tentativas ocorram ao mesmo tempo.

Lembre-se de que requisições malsucedidas contam para o limite por minuto, portanto, reenviar uma requisição continuamente não vai funcionar.

Os exemplos em Python abaixo demonstram o recuo usado como alternativa. Eles não verificam Retry-After: antes de usá-los, adicione o tratamento das indicações válidas do servidor para que as funções que envolvem as chamadas não tentem novamente antes do prazo solicitado. Desative as novas tentativas do SDK ou contabilize-as nos limites de novas tentativas da sua aplicação.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19from openai import OpenAI
from tenacity import (
    retry,
    stop_after_attempt,
    wait_random_exponential,
)  # for exponential backoff

client = OpenAI()


@retry(wait=wait_random_exponential(min=1, max=60), stop=stop_after_attempt(6))
def completion_with_backoff(**kwargs):
    return client.completions.create(**kwargs)


completion_with_backoff(
    model="gpt-3.5-turbo-instruct",
    prompt="Once upon a time,",
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import backoff
import openai
from openai import OpenAI

client = OpenAI()


@backoff.on_exception(backoff.expo, openai.RateLimitError)
def completions_with_backoff(**kwargs):
    return client.completions.create(**kwargs)


completions_with_backoff(
    model="gpt-3.5-turbo-instruct",
    prompt="Once upon a time,",
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59# imports
import random
import time

import openai
from openai import OpenAI

client = OpenAI()

# define a retry decorator


def retry_with_exponential_backoff(
    func,
    initial_delay: float = 1,
    exponential_base: float = 2,
    jitter: bool = True,
    max_retries: int = 10,
    errors: tuple = (openai.RateLimitError,),
):
    """Retry a function with exponential backoff."""

    def wrapper(*args, **kwargs):
        # Initialize variables
        num_retries = 0
        delay = initial_delay

        # Loop until a successful response or max_retries is hit or an exception is raised
        while True:
            try:
                return func(*args, **kwargs)

            # Retry on specific errors
            except errors:
                # Increment retries
                num_retries += 1

                # Check if max retries has been reached
                if num_retries > max_retries:
                    raise Exception(
                        f"Maximum number of retries ({max_retries}) exceeded."
                    )

                # Increment the delay
                delay *= exponential_base * (1 + jitter * random.random())

                # Sleep for the delay
                time.sleep(delay)

            # Raise exceptions for any errors not specified
            except Exception:
                raise

    return wrapper


@retry_with_exponential_backoff
def completions_with_backoff(**kwargs):
    return client.completions.create(**kwargs)

Reduza max_tokens para corresponder ao tamanho das suas respostas

Seu limite de taxa é calculado com base no maior valor entre max_tokens e o número estimado de tokens a partir da contagem de caracteres da sua requisição. Procure definir o valor de max_tokens o mais próximo possível do tamanho esperado da resposta.

Agrupamento de requisições em lotes

Se o seu caso de uso não exigir respostas imediatas, você pode usar a Batch API para enviar e executar grandes conjuntos de requisições com mais facilidade, sem afetar os limites de taxa das suas requisições síncronas.

Para casos de uso que exigem respostas síncronas, a API da OpenAI tem limites separados para requisições por minuto e tokens por minuto.

Se você estiver atingindo o limite de requisições por minuto, mas ainda tiver capacidade disponível em tokens por minuto, poderá aumentar sua taxa de processamento agrupando várias tarefas em cada requisição. Isso permitirá processar mais tokens por minuto, especialmente com nossos modelos menores.

Enviar um lote de prompts funciona exatamente como uma chamada normal à API, com a diferença de que você passa uma lista de strings ao parâmetro prompt em vez de uma única string. Saiba mais no guia da Batch API.