Limites de taxa

Os limites de taxa restringem o número de vezes que um usuário ou cliente pode acessar nossos serviços pela API em determinado período.

Por que temos limites de taxa?

O uso de limites de taxa é comum em APIs por vários motivos.

• Eles ajudam a proteger a API contra abusos e uso indevido. Por exemplo, alguém pode enviar um grande volume de solicitações à API para tentar sobrecarregá-la ou interromper o serviço. Ao definir limites de taxa, a OpenAI pode impedir esse tipo de atividade.
• Os limites de taxa ajudam a garantir acesso justo à API para todos. Se uma pessoa ou organização fizer solicitações em excesso, a API pode ficar lenta para os demais usuários. Ao limitar o número de solicitações por usuário, a OpenAI garante que o maior número possível de pessoas possa usar a API sem lentidão.
• Os limites de taxa ajudam a OpenAI a gerenciar a carga total da infraestrutura. Um aumento repentino no volume de solicitações à API pode sobrecarregar os servidores e prejudicar o desempenho. Com os limites de taxa, a OpenAI ajuda a manter o serviço estável e com bom desempenho para todos os usuários.

Como funcionam os limites de taxa?

Os limites de taxa usam métricas como RPM (solicitações por minuto), RPD (solicitações por dia), TPM (tokens por minuto), TPD (tokens por dia), IPM (imagens por minuto) e, em alguns modelos de streaming de áudio, minutos de áudio por minuto. Vale o limite que você atingir primeiro. Por exemplo, se você enviar 20 solicitações com apenas 100 tokens ao endpoint ChatCompletions em um minuto, atingirá um limite de 20 RPM, mesmo que essas solicitações fiquem abaixo do limite de 150 mil TPM.

Os limites de fila da Batch API são calculados com base no total de tokens de entrada na fila de cada modelo. Os tokens de lotes pendentes contam para o limite da fila. Quando o processamento de um lote termina, os tokens desse lote deixam de contar para o limite do modelo.

Outros detalhes importantes sobre os limites de taxa:

• Os limites de taxa se aplicam à organização e ao projeto, e não a cada usuário individualmente.
• Os limites de taxa variam conforme o modelo utilizado.
• Modelos com janela de contexto longa, como o GPT-5.5, têm um limite de taxa específico para solicitações com contexto longo. Você pode consultar esses limites no console do desenvolvedor.
• A OpenAI define um limite mensal de uso aprovado para cada organização. Esse limite é independente dos limites de gastos que você pode configurar para uma organização ou projeto.
• Algumas famílias de modelos compartilham limites de taxa. Na página de limites da organização, todos os modelos agrupados em um mesmo “limite compartilhado” usam o mesmo limite de taxa. Por exemplo, se o limite compartilhado for de 3,5 milhões de TPM, as chamadas a qualquer modelo desse grupo contam para o total de 3,5 milhões.
• A ingestão de dados também tem um limite de taxa por ID de armazenamento vetorial. Os endpoints /vector_stores/{vector_store_id}/files e /vector_stores/{vector_store_id}/file_batches compartilham um limite de 300 solicitações por minuto para cada armazenamento vetorial. Para ingerir volumes maiores, prefira /vector_stores/{vector_store_id}/file_batches.

Níveis de uso

Os três níveis de uso pagos são Build, Launch e Grow. Sua organização passa automaticamente para o nível seguinte quando o valor total das compras de créditos atinge o mínimo exigido para esse nível. Em geral, níveis mais altos oferecem limites de taxa maiores para os modelos.

Limites de taxa padrão

Para consultar os limites de cada modelo no seu nível de uso, acesse Configurações > Organização > Limites e consulte Limites de taxa. Para passar a um nível de uso superior, selecione Aumentar nível na seção Níveis de uso.

Os limites de taxa padrão são diferentes dos limites de taxa do modo ultrarrápido.

Limites de gastos

Considere definir limites de gastos para sua organização ou seus projetos a fim de controlar os gastos mensais com a API. Esses controles são independentes dos limites mensais de uso apresentados acima.

Limites de taxa nos cabeçalhos

Além de consultar os limites de taxa na página da sua conta, você pode verificar nos cabeçalhos da resposta HTTP quantas solicitações e quantos tokens ainda estão disponíveis, além de outros metadados sobre esses limites.

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 específico para o projeto. O cabeçalho Retry-After pode aparecer em respostas 429 causadas por um limite de taxa temporário e em respostas 503 causadas por uma sobrecarga temporária do modelo. A presença desse cabeçalho não significa que uma nova tentativa resolverá erros de cota, de cobrança ou outros que exijam uma ação do usuário.

Limites de taxa de ajuste fino

Você também pode consultar no painel os limites de taxa de ajuste fino da sua organização ou obtê-los pela API:

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

Disponibilidade dos modelos

O acesso aos modelos independe dos limites de taxa. Atingir o valor exigido para um nível de uso não garante acesso a todos os modelos. Se um modelo listado na documentação não aparecer no Playground ou na resposta de GET /v1/models, ou se uma solicitação retornar model_not_found, siga estas etapas:

1. Verifique o ID do modelo e o endpoint. Use o ID exatamente como aparece na documentação do modelo, confirme se o modelo é compatível com o endpoint que você usa e procure avisos de descontinuação ou de disponibilidade.
2. Compare a organização, o projeto e as credenciais. No Playground, selecione a organização e o projeto que você pretende usar. Faça uma chamada a Listar modelos com a mesma chave de API da solicitação que falhou. Se a solicitação incluía os cabeçalhos OpenAI-Organization ou OpenAI-Project, envie os mesmos cabeçalhos com os mesmos valores. Mesmo que um modelo apareça na sua sessão do painel, ele pode estar indisponível para outra chave de API.
3. Revise as restrições do projeto e os requisitos do modelo. Peça a alguém com permissão para gerenciar o projeto que verifique as permissões de acesso aos modelos e as configurações de retenção de dados do projeto. Cumpra os requisitos de acesso específicos do modelo e consulte os avisos sobre a liberação do modelo na documentação. A ausência do modelo, por si só, não indica a causa do problema.
4. Atualize e verifique novamente. Depois de alterar as configurações de acesso, atualize a lista de modelos ou o Playground. Se o modelo continuar indisponível, entre em contato com o suporte e informe o ID do modelo, os IDs da organização e do projeto, o horário da solicitação, a mensagem de erro e o valor do cabeçalho de resposta x-request-id, se disponível. Não compartilhe sua chave de API.

Mitigação de erros

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

A API pode retornar slow_down quando a taxa de solicitações aumenta rápido demais ou server_is_overloaded quando o modelo solicitado está temporariamente sobrecarregado. Verifique o status HTTP e o campo error.code para distinguir os dois casos.

Se o cabeçalho Retry-After estiver ausente, aumente o intervalo entre as tentativas e acrescente um pequeno atraso aleatório.

O erro slow_down pode ocorrer mesmo que o tráfego esteja dentro dos limites de solicitações por minuto e de tokens por minuto. Ele indica que o tráfego aumentou rápido demais, mesmo que esses limites ainda não tenham sido atingidos.

Como regra geral, quando o tráfego chegar a 1 milhão de tokens de entrada por minuto (TPM), limite o aumento a 50% a cada 15 minutos. O ponto exato em que o limite de crescimento do tráfego passa a valer pode variar conforme o modelo e as condições de tráfego.

Clientes Enterprise que pagam conforme o uso e atingem com frequência os limites de crescimento do tráfego podem considerar o Nível de escala para ter uma capacidade mais previsível nos modelos elegíveis. Para o GPT-5.6 e modelos posteriores, consulte o Nível reservado. Em qualquer nível de capacidade, o procedimento para uma resposta slow_down é o mesmo. Respeite o intervalo indicado em Retry-After, se presente, reduza o tráfego e volte a aumentá-lo gradualmente.

Atualize o tratamento de erros existente

Se seu aplicativo já tratava as respostas anteriores de limitação de tráfego e sobrecarga, verifique tanto o status HTTP quanto o campo error.code.

• Nos endpoints que antes retornavam 503 com o código slow_down para as duas situações, um aumento rápido de tráfego agora retorna 429 com slow_down. A sobrecarga do modelo continua retornando 503, mas agora usa server_is_overloaded.
• Nessas situações, as solicitações de vídeo rejeitadas antes da criação de uma tarefa retornavam 429 com o tipo invalid_request_error e o código rate_limit_exceeded. Agora, um aumento rápido de tráfego retorna 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 uma tarefa de vídeo são um caso à parte.

Trate tanto 429 quanto 503 nas rotinas de tratamento de erros do SDK. Por exemplo, os SDKs de Python, TypeScript e Ruby usam RateLimitError para 429 e InternalServerError para 503. O SDK de Java usa RateLimitException e InternalServerException, respectivamente. Mantenha o suporte aos códigos de resposta anteriores enquanto seu aplicativo ainda puder recebê-los. Como outros erros podem ter os mesmos status HTTP, examine o corpo do erro antes de decidir como proceder.

Nas solicitações de streaming, essas respostas de erro HTTP se aplicam antes do início da transmissão. Depois que a transmissão começa, um erro pode chegar como um evento do stream. Se você já consumiu parte da saída, não reenvie a solicitação automaticamente.

O que posso fazer para reduzir esses erros?

O OpenAI Cookbook tem um notebook em Python que explica como evitar erros de limite de taxa e um exemplo de script em Python que mostra como respeitar esses limites ao processar solicitações da API em lote.

Tenha cuidado ao oferecer acesso programático, recursos de processamento em lote ou publicação automática em redes sociais. Considere habilitar esses recursos apenas para clientes de confiança.

Para evitar o uso indevido por meio de automação ou em grande escala, defina um limite de uso por usuário para determinado período (diário, semanal ou mensal). Considere impor um teto rígido ou adotar um processo de revisão manual para os usuários que excederem o limite.

Novas tentativas com espera exponencial

Quando uma solicitação excede um limite de taxa temporário, a API retorna um erro 429. A resposta pode incluir o cabeçalho Retry-After, que indica quantos segundos aguardar antes de tentar novamente. Aguarde pelo menos o tempo indicado e acrescente um pequeno atraso aleatório para evitar que vários clientes tentem novamente ao mesmo tempo.

Cada SDK oficial da OpenAI repete automaticamente as solicitações que recebem respostas 429 e 503 elegíveis, conforme suas configurações de novas tentativas. A forma como o SDK trata Retry-After, especialmente quando a espera é longa, varia conforme a versão e a configuração. Verifique o comportamento da versão instalada antes de presumir que ela aceita qualquer intervalo indicado pelo servidor.

Se o intervalo indicado pelo servidor for válido, mas exceder o tempo máximo de espera aceito ou configurado para uma nova tentativa, interrompa as tentativas e adie a solicitação. Quando o intervalo excede o limite do SDK, ele pode retornar o erro HTTP original. Continue tratando separadamente os erros de cancelamento e de tempo limite. O cancelamento de uma solicitação ou o vencimento de um prazo pode interromper as tentativas sem retornar esse erro HTTP. O tempo limite de cada tentativa não determina necessariamente o prazo da operação inteira.

Se você usa seu próprio cliente HTTP, respeite o intervalo indicado em Retry-After quando o cabeçalho estiver presente e contiver um valor válido. Se o cabeçalho estiver ausente ou o valor for inválido, use espera exponencial com variação aleatória. Limite tanto o número de tentativas quanto o tempo total gasto nelas. Se o aplicativo gerencia as novas tentativas, desative as tentativas automáticas do SDK ou inclua-as nesses limites para evitar que a combinação dos dois mecanismos multiplique as solicitações. Não repita solicitações que falharam por problemas de cota, de cobrança ou por outros erros que exijam uma ação sua.

Na espera exponencial, você aguarda um breve intervalo após uma solicitação malsucedida e aumenta esse intervalo a cada nova tentativa que falha. O processo continua até que a solicitação tenha êxito ou atinja o limite configurado de tentativas.

Essa abordagem oferece várias vantagens:

• Com novas tentativas automáticas, é possível se recuperar de erros de limite de taxa sem travamentos nem perda de dados.
• A espera exponencial permite repetir a solicitação rapidamente nas primeiras tentativas e aguardar intervalos maiores caso elas falhem.
• Acrescentar uma variação aleatória ao intervalo ajuda a evitar que todas as novas tentativas ocorram ao mesmo tempo.

As solicitações malsucedidas contam para o limite por minuto, portanto reenviar continuamente a mesma solicitação não resolve o problema.

Os exemplos a seguir mostram como repetir uma solicitação ao modelo gpt-6-luna pela Responses API. Cada função que envolve a chamada à API limita o número de tentativas e desativa as novas tentativas automáticas do SDK.

Os exemplos em Python abaixo demonstram a estratégia de espera a usar na ausência de um intervalo válido indicado pelo servidor. Eles não verificam Retry-After. Antes de usá-los, acrescente a verificação dos intervalos válidos indicados pelo servidor para que as funções que repetem as solicitações respeitem a espera solicitada. Desative as novas tentativas do SDK ou inclua-as nos limites de tentativas do aplicativo.

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
28from openai import OpenAI, RateLimitError
from tenacity import (
    retry,
    retry_if_exception_type,
    stop_after_attempt,
    wait_random_exponential,
)  # for exponential backoff

client = OpenAI(max_retries=0)


@retry(
    retry=retry_if_exception_type(RateLimitError),
    wait=wait_random_exponential(min=1, max=60),
    stop=stop_after_attempt(6),
    reraise=True,
)
def response_with_backoff(**kwargs):
    return client.responses.create(**kwargs)


response = response_with_backoff(
    model="gpt-6-luna",
    input="Say hello in one sentence.",
    reasoning={"effort": "none"},
    max_output_tokens=64,
)
print(response.output_text)

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

client = OpenAI(max_retries=0)


@backoff.on_exception(backoff.expo, openai.RateLimitError, max_tries=6)
def response_with_backoff(**kwargs):
    return client.responses.create(**kwargs)


response = response_with_backoff(
    model="gpt-6-luna",
    input="Say hello in one sentence.",
    reasoning={"effort": "none"},
    max_output_tokens=64,
)
print(response.output_text)

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
60
61
62
63
64
65
66
67
68# imports
import random
import time

import openai
from openai import OpenAI

client = OpenAI(max_retries=0)

# 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 response_with_backoff(**kwargs):
    return client.responses.create(**kwargs)


response = response_with_backoff(
    model="gpt-6-luna",
    input="Say hello in one sentence.",
    reasoning={"effort": "none"},
    max_output_tokens=64,
)
print(response.output_text)

Reduza max_tokens de acordo com o tamanho das respostas

O cálculo do limite de taxa considera o maior entre dois valores: max_tokens e o número de tokens estimado a partir da contagem de caracteres da solicitação. Procure definir max_tokens com um valor o mais próximo possível do tamanho esperado da resposta.

Agrupamento de solicitações em lotes

Se seu caso de uso dispensar respostas imediatas, você pode usar a Batch API para enviar e executar grandes lotes de solicitações sem afetar os limites de taxa das solicitações síncronas.

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

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

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