Limites de taxa

Limitação de taxa por carteira para operações com ordens e requisições à API.

Visão geral

A limitação de taxa usa janelas fixas de 60 segundos. Os limites por carteira vêm do nível (tier) da carteira e são aplicados a:

• Envio de ordens (POST /order, PUT /order, WebSocket PlaceOrder e envios de ordens de perpétuos pela rota TEE)
• Cancelamento de ordens (DELETE /order, DELETE /order_cloid e cancelamentos de perpétuos pela rota TEE)
• Requisições à API (leituras vinculadas à carteira e outras escritas assinadas)

Limites separados, indexados pela origem de rede e com um teto global por processo, se aplicam a cancelamentos, autorização de agentes, escritas de MMP e simulações públicas de risco.

Os contadores são mantidos em memória por cada processo da API. Eles não são compartilhados entre réplicas, então trate os números publicados como o máximo que um único processo aceitará, e não como um orçamento para todo o cluster.

Limites padrão

Nível	Ordens/min	Cancelamentos/min	Requisições à API/min	Máx. de ordens abertas	Máx. de posições
Padrão	60	120	600	100	50
Tier 1	30	60	300	50	20
Tier 2	120	300	1.200	500	200
Market Maker	1.200	2.400	6.000	5.000	Ilimitado

Novas carteiras recebem os limites padrão. Entre em contato com o suporte para upgrades de nível. Seu limite atual de requisições à API aparece no cabeçalho X-RateLimit-Limit de qualquer leitura vinculada à carteira, por exemplo GET /orders?wallet=....

Resposta de limite de taxa

Quando um limite de taxa é excedido, a API retorna 429 Too Many Requests:

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded for OrderPlacement: 60 per minute, retry after 45 seconds",
  "retry_after_secs": 45,
  "limit": 60
}

Cabeçalhos de resposta

Endpoints com limite por carteira retornam estes cabeçalhos. Uma resposta 429 traz X-RateLimit-Limit, X-RateLimit-Remaining: 0 e Retry-After, mas não X-RateLimit-Reset:

Cabeçalho	Descrição	Exemplo
X-RateLimit-Limit	Máximo de requisições permitidas por janela	60
X-RateLimit-Remaining	Requisições restantes na janela atual	42
X-RateLimit-Reset	Timestamp Unix em segundos de quando a janela é reiniciada (apenas em respostas de sucesso)	1737312060
Retry-After	Segundos até poder tentar novamente (apenas em 429)	45

Exemplo de cabeçalhos de resposta

Requisição bem-sucedida:

HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1737312060

Requisição limitada:

HTTP/1.1 429 Too Many Requests
Retry-After: 45
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0

Categorias de limite de taxa

Os limites de taxa são contabilizados separadamente para cada tipo de ação:

Envio de ordens

Contabilizado por carteira contra o limite de Ordens/min do nível:

• POST /order e PUT /order
• WebSocket PlaceOrder
• POST /v1/tee-perp/orders/submit e os demais envios de ordens de perpétuos, contabilizados contra o manager da conta

POST /bulk_order e PUT /bulk_order são limitados a 50 entradas por requisição.

Cancelamento de ordens

Contabilizado por carteira contra o limite de Cancelamentos/min do nível:

• DELETE /order e DELETE /order_cloid
• Cancelamentos de perpétuos, contabilizados contra a carteira de API que assina

Toda rota de cancelamento, incluindo DELETE /bulk_order e DELETE /bulk_order_cloid, também é limitada antes da verificação de assinatura a 6.000 pernas de cancelamento por origem de rede e 60.000 pernas por processo, por minuto. Um cancelamento em lote conta uma perna por entrada.

Requisições à API

Contabilizado por carteira contra o limite de Requisições à API/min do nível:

• Leituras vinculadas à carteira, indexadas pelo parâmetro de consulta wallet
• Escritas assinadas não listadas acima, como configuração de MMP e modo de margem

Envio de RFQ

POST /rfq/request e os comandos de envio de RFQ via WebSocket são limitados a 10 por carteira por minuto, independentemente do nível.

Simulação de risco

Simulações públicas de portfólio e de ordens (POST /risk/simulate/portfolio, POST /risk/simulate/orders e a prévia de perpétuos POST /v1/tee-perp/preview) têm limites separados de 60 requisições por origem de rede e 600 requisições por processo, por minuto. No máximo quatro simulações são executadas simultaneamente em um processo da API. Uma requisição que excede uma cota ou encontra os workers de simulação saturados retorna 429 Too Many Requests.

Autorização de agentes

POST /approve-agent, DELETE /revoke-agent e DELETE /revoke-all-agents são limitados antes da verificação de assinatura a 120 requisições por origem de rede e 1.200 requisições por processo, por minuto.

Escritas de MMP

Escritas de configuração de MMP são limitadas antes da verificação de assinatura a 120 requisições por origem de rede e 1.200 requisições por processo, por minuto, além do limite de requisições à API da carteira.

Limites de posições e ordens

Além dos limites de taxa, as carteiras têm limites máximos de ordens abertas e de posições:

Tipo de limite	Descrição	Rejeição
Máx. de ordens abertas	Máximo de ordens abertas simultâneas	Nova ordem rejeitada enquanto a carteira estiver no limite
Máx. de posições	Máximo de posições únicas (-1 = ilimitado)	Ordem rejeitada se abrir uma nova posição

Essas são rejeições de ordem, não erros HTTP. A resposta da ordem é HTTP 200 com status: "REJECTED" e um reason como:

max_open_orders_exceeded: current=100, limit=100
max_positions_exceeded: wallet 0x... has 50 positions, limit is 50

Boas práticas

Lidando com limites de taxa

1. Monitore os cabeçalhos: acompanhe X-RateLimit-Remaining de forma proativa
2. Respeite o Retry-After: aguarde o tempo indicado antes de tentar novamente
3. Implemente backoff: use backoff exponencial em respostas 429 repetidas

import time

def place_order_with_retry(order, max_retries=3):
    for attempt in range(max_retries):
        response = api.place_order(order)

        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 60))
            time.sleep(retry_after)
            continue

        return response

    raise RateLimitError("Max retries exceeded")

Otimizando o uso de requisições

1. Use endpoints em lote: POST /bulk_order para várias ordens em uma única requisição
2. Cancele em lote: DELETE /bulk_order ou DELETE /bulk_order_cloid em vez de várias requisições DELETE /order
3. WebSocket para atualizações: assine as atualizações de ordens em vez de fazer polling em GET /orders

Monitoramento

Acompanhe estas métricas no lado do cliente:

• Taxa de requisições por tipo de ação
• Tendências de X-RateLimit-Remaining
• Frequência de respostas 429
• Duração média de Retry-After

Referência de erros

Status HTTP	Código de erro	Descrição
429	rate_limit_exceeded	Limite de taxa excedido, tente novamente após o tempo indicado

Veja Erros para a referência completa de erros.