Rate Limits

Limites por ambiente

| Ambiente | Limite | Janela | |---|---|---| | Produção (sk_live_) | 100 requisições | Por minuto, por chave | | Sandbox (sk_sandbox_) | 100 requisições | Por minuto, por chave |

Os limites são aplicados por API Key. Se você tiver múltiplas integrações, use chaves distintas para ter limites independentes.

Headers de rate limit

Todas as respostas incluem headers indicando o estado atual do limite:

X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1705323660

| Header | Descrição | |---|---| | X-RateLimit-Limit | Limite total por janela | | X-RateLimit-Remaining | Requisições restantes na janela atual | | X-RateLimit-Reset | Timestamp Unix quando a janela reinicia |

Resposta quando o limite é atingido

Ao exceder o limite, a API retorna 429 Too Many Requests:

  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Limite de requisições atingido. Tente novamente em 23 segundos."
  }
}

O header Retry-After indica quantos segundos aguardar:

Retry-After: 23

Implementando respeito ao rate limit

  const response = await fetch(url, options)
 
  if (response.status === 429) {
    const retryAfter = parseInt(response.headers.get('Retry-After') || '60')
    console.log(`Rate limit atingido. Aguardando ${retryAfter}s...`)
    await new Promise(r => setTimeout(r, retryAfter * 1000))
    return apiRequest(url, options) // tenta novamente
  }
 
  return response
}

Boas práticas para não atingir o limite

• Evite polling: Use webhooks para receber atualizações de status em vez de consultar /charges/:txid repetidamente
• Cache o saldo: O saldo não muda a cada segundo — armazene em cache por 30–60 segundos
• Paginação eficiente: Ao listar transações, use limit adequado em vez de fazer muitas requisições com limite pequeno
• Filas de processamento: Para processar muitas transações em lote, use uma fila com rate limiting

Aumentar o limite

Se sua integração requerer um limite maior, entre em contato com suporte@cyrus.com informando:

• Volume esperado de requisições por minuto
• Casos de uso específicos
• Ambiente (produção ou sandbox)