Você lança uma função que chama a API GPT. Ela funciona bem em staging. Os primeiros cem usuários a acessam em produção, e seus logs se enchem de 429 Too Many Requests. Agora você está adivinhando: são requisições por minuto, tokens por minuto ou limites diários? Você ainda está no nível 1? O modelo para o qual você mudou na semana passada tinha limites mais rigorosos do que o anterior?
Se você já trabalhou com OpenAI antes, sabe que a história dos limites de taxa se tornou mais complicada a cada novo modelo. O GPT-5.5 tem limites diferentes do GPT-4.1, modelos de imagem contam de forma diferente dos modelos de texto, e seu nível de uso muda silenciosamente à medida que seus gastos aumentam. O Apidog oferece um único espaço de trabalho para inspecionar os cabeçalhos de resposta de cada requisição, simular tráfego concorrente e confirmar exatamente qual limite você está atingindo antes de enviar o código. Baixe o Apidog se ainda não o tem; o fluxo de trabalho abaixo funciona no plano gratuito.
Os quatro limites que realmente importam
A OpenAI aplica vários limites de taxa a cada chave de API GPT. Você verá todos os quatro impostos para qualquer aplicação em produção:
- RPM (requisições por minuto): o número de chamadas de API que você pode enviar por minuto. O limite mais baixo na maioria dos níveis.
- TPM (tokens por minuto): a soma de tokens de entrada e saída que você pode processar por minuto. O limite que a maioria das pessoas esquece.
- RPD (requisições por dia): um teto diário para chaves gratuitas e de nível 1. Desaparece em níveis superiores para a maioria dos modelos de texto.
- IPM / TPD / limites de fila de lote: limites específicos do modelo para geração de imagens, áudio, embeddings e endpoints de lote. Cada família de endpoints tem seu próprio teto.
Quando sua requisição é recusada, a API retorna HTTP 429 e um corpo JSON como este:
{
"error": {
"message": "Rate limit reached for gpt-5.5 in organization org-abc on tokens per min (TPM): Limit 30000, Used 28432, Requested 3120.",
"type": "tokens",
"param": null,
"code": "rate_limit_exceeded"
}
}
Observe que o corpo informa qual dimensão você excedeu: tokens, requests, ou às vezes tokens_usage_based. Essa é a primeira coisa que você lê quando algo falha. O erro de um estouro de TPM parece diferente de um estouro de RPM, e a correção também é diferente. Um 429 não é um 429 não é um 429.
Para uma referência completa sobre o que 429 significa no nível HTTP, consulte a documentação MDN 429 e a especificação RFC 6585. Para o comportamento específico da OpenAI em relação aos cabeçalhos de repetição e movimento de níveis, a OpenAI mantém uma página oficial de limites de taxa que você deve adicionar aos favoritos.
Como funcionam os níveis e por que você continua sendo promovido (ou preso)
Sua chave de API GPT está inserida em um nível de uso da OpenAI. Os níveis determinam os números reais por trás dos seus limites de RPM e TPM. Você sobe de nível com base em duas coisas: o gasto total em sua conta e há quanto tempo você pagou pela primeira vez. Existem seis níveis, do gratuito ao nível 5, e a estrutura aproximada é esta para modelos de texto:
| Nível | Gasto mínimo | Período de espera | RPM de texto | TPM de texto |
|---|---|---|---|---|
| Grátis | nenhum | nenhum | 3 | 40k |
| 1 | $5 pagos | nenhum | 500 | 30k–200k por modelo |
| 2 | $50 pagos | 7 dias | 5.000 | 450k |
| 3 | $100 pagos | 7 dias | 5.000 | 1M |
| 4 | $250 pagos | 14 dias | 10.000 | 2M |
| 5 | $1.000 pagos | 30 dias | 10.000 | 2M+ |
Os números acima são ilustrativos; os limites exatos mudam com o tempo e variam por modelo. Leia seus limites em tempo real diretamente do painel ou, melhor ainda, dos cabeçalhos de resposta da sua própria API (abordado abaixo) antes de dimensionar uma carga de trabalho.
Duas implicações práticas:
- Você é promovido automaticamente ao pagar. Os níveis não são opcionais. No momento em que seu gasto ultrapassa um limite de nível e o período de espera passou, a próxima requisição que você faz é executada contra os novos limites. Sem notificação, sem etapa de migração.
- Você pode ser rebaixado. Se sua conta ficar inativa por um longo período ou seu método de pagamento falhar, você pode cair para um nível inferior. Teste em produção após qualquer alteração de cobrança.
Para uma comparação lado a lado com os sistemas de níveis de outros provedores de modelos, consulte nosso explicador de limites de taxa de usuário da API OpenAI, o guia de limites de taxa da API Claude e o guia de limites de taxa da API Grok-3. O modelo mental é o mesmo entre os provedores; os números e dimensões específicas não são.
Leia seus limites em tempo real dos cabeçalhos de resposta
Você não precisa vasculhar painéis para encontrar seus limites atuais. Toda resposta da API GPT os carrega nos cabeçalhos. Procure por estes quatro:
x-ratelimit-limit-requests: seu limite de RPM para este endpoint.x-ratelimit-remaining-requests: quantas você ainda tem neste minuto.x-ratelimit-limit-tokens: seu limite de TPM.x-ratelimit-remaining-tokens: quantos tokens você ainda tem neste minuto.
Geralmente, também há x-ratelimit-reset-requests e x-ratelimit-reset-tokens, ambos fornecendo uma duração legível até que o "balde" seja reabastecido (por exemplo, 6s, 1m30s).
A maneira mais limpa de ler isso é enviar uma única requisição de chat-completion, observar os cabeçalhos retornarem e confirmar que você está no nível que pensa estar. O Apidog torna isso um único clique.
Passo 1: configure a requisição GPT no Apidog
Abra o Apidog, crie um novo projeto e adicione uma nova requisição dentro dele.
Método: POST URL: https://api.openai.com/v1/chat/completions
Na aba Headers:
| Chave | Valor |
|---|---|
Authorization |
Bearer {{OPENAI_API_KEY}} |
Content-Type |
application/json |
A sintaxe de chaves duplas puxa de uma variável de ambiente do Apidog, o que significa que sua chave nunca reside dentro da própria requisição. Defina a variável uma vez em Environments, troque de ambientes para alternar entre chaves pessoais e de equipe, e o resto da coleção será atualizado automaticamente. O mesmo truque funciona para os IDs de organização e projeto que a OpenAI permite que você inclua para atribuição de faturamento.
Na aba Body, escolha JSON e cole:
{
"model": "gpt-5.5",
"messages": [
{"role": "user", "content": "ping"}
],
"max_tokens": 10
}
Clique em Send. Você deve receber uma conclusão normal de volta. Agora clique na aba Headers no painel de resposta e role até as linhas x-ratelimit-*. Esses quatro números são sua verdade atual. Tire um print. Eles são a linha de base contra a qual você testará.
Se preferir detalhar a configuração da requisição de chat-completion, nosso guia sobre como testar a API ChatGPT com Apidog aborda autenticação, streaming e chamadas de ferramentas de ponta a ponta.
Passo 2: confirme os limites com um pico deliberado
Ler os cabeçalhos informa o limite. Enviar uma única requisição não prova nada sobre o comportamento no limite. Para verificar se o estrangulamento realmente entra em ação onde os cabeçalhos indicam, você precisa de um pequeno teste de pico.
O Apidog vem com um executor de Testes que pode disparar a mesma requisição N vezes concorrentemente. Abra sua requisição salva, clique no menu suspenso ao lado de Send e escolha Run in Test Scenario. Defina:
- Iterações: 50 (ou o que estiver confortavelmente acima do seu RPM declarado)
- Concorrência: 10
- Atraso entre iterações: 0 ms
Execute. Dois resultados são úteis:
- Algumas requisições retornam 429 antes do pico terminar. Bom. Isso confirma que o limite do cabeçalho de resposta e o estado da sua conta estão sincronizados.
- Todas as 50 são bem-sucedidas e os cabeçalhos mostram
remaining-requestsdiminuindo conforme o esperado. Seu RPM é maior do que você pensava; verifique o painel de resposta para o valor exato.
O executor de testes do Apidog registra cada resposta, então você pode ordenar por código de status e reunir todos os 429 em uma única visualização. Clique em uma linha 429 e leia seu corpo. O campo message informa se você excedeu o RPM, TPM ou um limite diário. Essa é a dimensão contra a qual você dimensiona em seu código de produção.
Para uma introdução sobre o que fazer ao atingir o limite, o guia de limite de taxa excedido percorre todas as superfícies de 429 que você provavelmente verá.
Passo 3: separe os estouros de RPM dos estouros de TPM
O primeiro pico acima mede o RPM, porque cada requisição é minúscula. Para sondar o TPM, você precisa disparar menos requisições, mas cada uma maior. Edite o corpo da sua requisição para que messages carregue um payload muito maior:
{
"model": "gpt-5.5",
"messages": [
{"role": "system", "content": "<3,000 tokens de contexto aqui>"},
{"role": "user", "content": "Resuma o acima em uma frase."}
],
"max_tokens": 200
}
Execute outro cenário, desta vez com talvez 20 iterações em concorrência 5. Se você estiver no nível 1 com um limite de TPM de 30k, você atingirá os limites de tokens muito antes de atingir os limites de requisições.
Essa separação é importante porque a solução é diferente. Se sua carga de trabalho real envia muitas requisições pequenas, corrija o RPM: enfileire, agrupe ou escalone. Se ela envia menos requisições grandes, corrija o TPM: corte prompts de sistema, armazene contextos em cache com o mecanismo prompt_cache ou divida a requisição.
Passo 4: simule usuários concorrentes
Testes de pico medem seu próprio teto. O tráfego de produção parece diferente: muitos usuários, tamanhos de requisição variados, picos sobre uma linha de base estável.
No Apidog, crie um cenário de teste que percorre três ou quatro variações da requisição (pequena, média, grande) com pausas aleatórias entre as iterações. O executor suporta scripts JavaScript de pré e pós-requisição, então você pode:
- Escolher um comprimento de mensagem aleatório por iteração.
- Ler
x-ratelimit-remaining-tokensapós cada resposta e abortar o cenário quando ele cair abaixo de um limite. - Registrar a latência separadamente para 200s versus 429s para que você possa ver como o estrangulamento arrasta o p95.
Quando o cenário terminar, o relatório fornecerá um histograma de códigos de status. Esse histograma é o artefato mais útil que você pode fixar em um runbook. No momento em que um colega de trabalho perguntar “estamos com limite de taxa?”, você o executa novamente e compara.
O que fazer quando você é limitado (throttled)
Depois de medir onde está a barreira, você tem três opções honestas.
Recue. Embrulhe cada chamada GPT em uma lógica de repetição com backoff exponencial. Leia o cabeçalho x-ratelimit-reset-tokens da resposta 429 e use-o como seu primeiro atraso de repetição; esse cabeçalho é a resposta literal da OpenAI para “espere por este tempo”. Um time.sleep(2 ** attempt) ingênuo também funciona, mas desperdiça segundos que você não precisava esperar.
Enfileire. Se o seu tráfego for em picos, coloque as requisições em uma fila e as esgote a uma taxa ligeiramente abaixo do seu limite. Um limitador tipo 'token-bucket' fixado um pouco abaixo do seu TPM é o padrão. Discutimos as compensações de implementação em como implementar limite de taxa de API e implementando limite de taxa em APIs.
Em lote. A API de Lote da OpenAI funciona com limites mais altos e pela metade do preço das chamadas síncronas. Se sua carga de trabalho tolera um tempo de resposta de 24 horas (enriquecimento noturno, classificação de documentos, reconstrução de embeddings), mova-a para o Lote e libere sua cota síncrona para o tráfego voltado para o usuário.
Se você quiser uma leitura mais aprofundada sobre a distinção entre throttling e rate-limiting antes de escolher um, throttling vs. limite de taxa é o caminho mais curto pela terminologia.
Erros comuns de GPT 429 e o que eles significam
Três tipos de 429 cobrem aproximadamente 90% dos casos do mundo real.
Limite de taxa atingido … em requisições por minuto (RPM) significa que seu código está disparando muitas chamadas por minuto, independentemente do tamanho. Adicione controle de concorrência. Não dispare cada registro em um map paralelo; limite seu pool de workers ao seu RPM dividido por um fator de segurança de dois.
Limite de taxa atingido … em tokens por minuto (TPM) significa que suas chamadas são muito grandes. Audite o prompt. A maioria dos estouros de TPM vem de prompts de sistema que cresceram ao longo do tempo ou de pipelines RAG que inserem documentos inteiros no contexto. Corte, armazene em cache ou divida.
Você excedeu sua cota atual, por favor, verifique seu plano e detalhes de faturamento parece um 429, mas na verdade é uma barreira de faturamento, não um limite de taxa. Sua conta atingiu um limite de gastos mensais, o cartão cadastrado falhou ou o saldo pré-pago chegou a zero. A solução está no painel de faturamento, não no seu código.
FAQ
O Apidog custa algo para testar os limites de taxa do GPT? Não. O plano gratuito cobre testes de requisição única e pequenas execuções de teste concorrentes. Você só precisa de um plano pago se quiser cargas de teste maiores, espaços de trabalho em equipe ou execuções agendadas. Veja os preços do Apidog para mais detalhes.
Posso testar limites de taxa sem queimar tokens reais? Parcialmente. A verificação de linha de base mais barata é uma requisição única com max_tokens: 1 e uma mensagem de um caractere; custa frações de centavo e os cabeçalhos retornam completos. Para testes de pico, você gasta tokens reais, mas pode manter cada chamada minúscula. Se você quiser um ensaio totalmente offline, use o mock server do Apidog para simular o formato da resposta 429 e provar que sua lógica de repetição funciona sem chamar a OpenAI.
Por que minha chave de nível 1 parece mais lenta do que a de um colega de nível 1? Os limites de nível são por organização, não por chave. Se sua chave estiver em uma organização compartilhada com outros usuários pesados, você estará competindo com o tráfego deles. O Apidog pode mostrar isso claramente: execute a mesma requisição de ambas as chaves lado a lado e compare o decaimento de x-ratelimit-remaining-tokens.
Como sei qual modelo tem qual limite? Leia os cabeçalhos de resposta. Não confie em tabelas genéricas em posts de blog (incluindo este). Faça uma requisição barata para cada modelo usando o Apidog e registre os cabeçalhos. Modelos com o mesmo nome, mas diferentes versões de snapshot (por exemplo, gpt-5.5 vs gpt-5.5-0901) podem ter limites diferentes.
As requisições de streaming contam de forma diferente? Sim para TPM. Uma requisição de streaming reserva tokens antecipadamente com base em max_tokens, então um valor alto de max_tokens pode consumir seu orçamento de TPM mesmo que a conclusão real tenha sido curta. Reduza max_tokens para o teto realista mais justo. Cobrimos o comportamento de streaming em como testar a API ChatGPT com Apidog.
Posso compartilhar meu teste de limite de taxa do Apidog com minha equipe? Sim. Salve a requisição e o cenário de teste em um projeto compartilhado. Qualquer pessoa em seu espaço de trabalho pode executar o mesmo teste de pico contra sua própria chave trocando de ambientes. Isso transforma “minha chave está limitada ou a deles?” em uma pergunta de 10 segundos.