Limites de taxa

Os limites de taxa protegem seu saldo e o serviço. Os limites são contados em requisições por minuto (RPM) por chave de API, e as chaves também podem ter um limite diário de gasto em USD.

Limites por plano

Faça upgrade na página de preços para aumentar seu limite.

Limites por chave

Ao criar ou editar uma chave em Chaves de API, você pode definir:

A janela de RPM é de um minuto e é contada por chave, então chaves separadas para apps separados não compartilham um limite, mas toda chave continua limitada pelo limite do seu plano.

Cabeçalhos de limite

Cada resposta de geração (sucesso ou erro) mostra onde você está, para reduzir o ritmo antes de atingir o limite:

Clientes de navegador também podem lê-los (estão em Access-Control-Expose-Headers).

Picos e concorrência

Pedidos acima do limite não são recusados na hora: esperam numa fila e começam assim que a janela de um minuto libera. Até 10 pedidos por conta rodam ao mesmo tempo; os demais esperam um terminar. Antes de começar, o custo máximo estimado do pedido é reservado do seu saldo junto com o dos pedidos em andamento, então pedidos paralelos nunca gastam mais do que você tem. Um pedido que não consegue começar em 60 segundos retorna 429 (rate_limited ou concurrency_limit) com Retry-After; se o custo não cabe mais no saldo, retorna 402 insufficient_balance.

Novas tentativas seguras com Idempotency-Key

Depois de um erro de rede você pode não saber se a solicitação chegou. Envie um cabeçalho Idempotency-Key (uma string única de até 120 caracteres, por exemplo um UUID) e tente de novo com a mesma chave: se a primeira solicitação já foi enviada ao modelo, a nova tentativa retorna 409 idempotency_conflict em vez de executar e cobrar o trabalho duas vezes. Se a primeira falhou antes de chegar ao modelo, a chave é liberada e a nova tentativa funciona normalmente. Uma chave pode ser usada uma vez por conta durante 24 horas.

curl https://api14.com/api/v1/images/generations \
  -H "Authorization: Bearer $API14_KEY" \
  -H "Idempotency-Key: 6f1c2a3e-order-1842" \
  -H "Content-Type: application/json" \
  -d '{"model": "black-forest-labs/flux-3-image", "prompt": "a red bicycle"}'

Quando você atinge um limite

Requisições demais

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "error": {
    "message": "Rate limit of 5 requests per minute exceeded.",
    "type": "rate_limit_error",
    "code": "rate_limited"
  }
}

Aguarde o número de segundos indicado em Retry-After e tente de novo. Os SDKs oficiais da OpenAI repetem automaticamente as respostas 429 com backoff (duas tentativas por padrão; configure com maxRetries / max_retries).

Limite diário de gasto

{
  "error": {
    "message": "This API key reached its daily spend limit.",
    "type": "rate_limit_error",
    "code": "daily_limit_reached"
  }
}

Tentar de novo não adianta até o próximo dia UTC. Aumente ou remova o limite diário da chave em Chaves de API se esse tráfego for esperado.

Limites do upstream

Os provedores têm seus próprios limites, que são mais rígidos para as variantes de modelo :free. Quando um provedor limita uma requisição, o 429 dele é repassado a você. Use fallbacks de modelo ou roteamento de provedores para distribuir a carga entre provedores.

Tratando limites no código

• Respeite o Retry-After e tente de novo com backoff exponencial e jitter.
• Diferencie rate_limited (tente mais tarde) de daily_limit_reached e insufficient_balance (tentar de novo não adianta).
• Coloque jobs em segundo plano em fila em vez de disparar todos de uma vez.
• Use streaming para respostas longas: uma requisição com streaming conta como uma requisição.

import time
from openai import OpenAI, RateLimitError

client = OpenAI(base_url="https://api14.com/api/v1", api_key="sk-api14-...", max_retries=0)

for attempt in range(5):
    try:
        r = client.chat.completions.create(model="openai/gpt-5-mini", messages=[{"role": "user", "content": "Hi"}])
        break
    except RateLimitError as e:
        if e.code == "daily_limit_reached":
            raise
        time.sleep(int(e.response.headers.get("retry-after", 2 ** attempt)))

Veja Erros para todos os códigos de status.