Rate Limits

O Tokia aplica limites de taxa (rate limits) para garantir estabilidade e uso justo da plataforma. Os limites existem por chave de API, por modelo e por conta.

Tipos de limite

Limites padrão por nível

O nível sobe automaticamente conforme o saldo acumulado (total já recarregado, não o saldo atual). O nível nunca desce.

Headers de rate limit

Cada resposta da API inclui headers indicando o estado do limite:

Erro 429: Too Many Requests

Quando você excede o limite, a API retorna 429:

{
  "error": {
    "message": "Rate limit exceeded. Please retry after 2 seconds.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

O header retry-after indica quantos segundos esperar.

Estratégias de retry e backoff

Exponential backoff

A estratégia recomendada: esperar 1s, depois 2s, 4s, 8s... até um máximo. Os SDKs OpenAI já implementam isso automaticamente:

from openai import OpenAI

# O SDK OpenAI já faz retry com exponential backoff por padrão
# Basta configurar max_retries:
client = OpenAI(
    api_key="sk-...",
    base_url="https://api.usetokia.com/v1",
    max_retries=3,
    timeout=60,
)

Retry manual (Python)

import time
from openai import OpenAI, RateLimitError

client = OpenAI(
    api_key="sk-...",
    base_url="https://api.usetokia.com/v1",
    max_retries=0,  # desligar retry automático para controlar manualmente
)

def call_with_backoff(messages, max_retries=5):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model="gpt-4o-mini",
                messages=messages,
            )
        except RateLimitError as e:
            if attempt == max_retries - 1:
                raise
            wait = 2 ** attempt  # 1, 2, 4, 8, 16 segundos
            print(f"Rate limited, aguardando {wait}s...")
            time.sleep(wait)

response = call_with_backoff([{"role": "user", "content": "Olá"}])

Retry (TypeScript)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOKIA_KEY,
  baseURL: "https://api.usetokia.com/v1",
  maxRetries: 3,
  timeout: 60_000,
});

Dicas para evitar rate limiting

• Use batch quando possível: uma chamada com 5 mensagens é melhor que 5 chamadas separadas (1 RPM vs 5 RPM)
• Cache respostas: se a mesma pergunta vai ser feita várias vezes, cache o resultado
• Distribua carga: se possível, use múltiplas API keys para distribuir requisições
• Modelos menores: gpt-4o-mini tem limites mais generosos que gpt-4o porque consome menos TPM
• Monitore os headers: verifique x-ratelimit-remaining-* e reduza a velocidade antes de bater o limite

Rate limit vs saldo insuficiente

Não confunda os dois erros:

Precisa de limites maiores?

Se os limites padrão não atendem a sua aplicação, entre em contato pelo contato@usetokia.com com o volume estimado (RPM e TPM) para avaliar um limite personalizado.

Próximos passos

• Códigos de erro — referência completa de erros da API
• Preços e markup — como o preço por modelo funciona
• Quickstart — primeira chamada em 3 minutos