Limitation de Taux

Limites de requêtes API et gestion automatique par nos SDK officiels.

📊 Aperçu

Sharokey implémente une limitation de taux pour assurer un usage équitable et protéger notre infrastructure. Nos SDK gèrent automatiquement tous les scénarios de limitation de taux avec une logique de nouvelle tentative intégrée et un backoff exponentiel.

SDK Officiels :

• Outil CLI C# - Interface en ligne de commande multiplateforme
• JavaScript SDK - Pour Node.js et les applications web modernes
• JavaScript CDN - Intégration navigateur simple
• Python SDK - Client Python asynchrone

🚦 Limites de Taux par Opération

Opérations d'Authentification

• Limite : 10 requêtes par minute
• Portée : Par token
• Gestion SDK : Nouvelle tentative automatique avec backoff exponentiel

Gestion des Secrets

• Limite : 30 requêtes par minute
• Portée : Par token
• Gestion SDK : File d'attente de requêtes et batching intelligent

Opérations de Tokens d'Entreprise

• Limite : 5 requêtes par minute
• Portée : Par token
• Gestion SDK : Traitement séquentiel avec délais

🛠️ Gestion des Limites de Taux SDK

Tous nos SDK gèrent automatiquement les limites de taux sans aucune configuration requise :

Limitation de Taux CLI C#

# Le CLI réessaie automatiquement quand limité par le taux
sharokey create "content" --hours 24 --views 1
# Si limité : "Limite de taux atteinte, nouvelle tentative dans 30 secondes..."

# Les opérations en masse sont automatiquement throttlées
sharokey bulk-create secrets.json
# Traite par lots avec délais automatiques

Limitation de Taux JavaScript SDK

// Le SDK gère automatiquement les limites de taux
const client = new SharokeyClient({ token: 'your_token' });

try {
  // Ceci réessaiera automatiquement si limité par le taux
  const secret = await client.createSecret("content", {
    hours: 24, views: 1
  });
  console.log(secret.share_url);
} catch (error) {
  // Les erreurs de limite de taux sont gérées automatiquement
  // Seules les erreurs irrécupérables atteignent ce point
  console.error('Échec après nouvelles tentatives :', error.message);
}

// Opérations en masse avec throttling automatique
const secrets = await Promise.all([
  client.createSecret("secret 1", { hours: 24 }),
  client.createSecret("secret 2", { hours: 24 }),
  client.createSecret("secret 3", { hours: 24 })
  // Le SDK espace automatiquement ces requêtes
]);

Limitation de Taux Python SDK

import sharokey

client = sharokey.SharokeyClient(token='your_token')

try:
    # Nouvelle tentative et backoff automatiques
    secret = await client.create("content", hours=24, views=1)
    print(secret.share_url)
except sharokey.RateLimitError as e:
    # Ceci devrait rarement arriver grâce à la gestion automatique
    print(f"Limité par le taux même après nouvelles tentatives : {e}")

# Opérations en masse avec batching automatique
secrets_data = [
    {"content": "secret 1", "hours": 24},
    {"content": "secret 2", "hours": 24},
    {"content": "secret 3", "hours": 24}
]

# Le SDK batch et throttle automatiquement ces requêtes
secrets = await client.create_batch(secrets_data)

🚨 Réponses de Limite de Taux

Quand les limites de taux sont dépassées, vous recevrez ce format d'erreur :

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Trop de requêtes. Veuillez réessayer plus tard.",
    "details": {
      "retry_after": 30,
      "limit": 30,
      "window": 60,
      "reset_at": "2025-08-11T19:30:00Z"
    }
  }
}

Headers de Réponse :

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640995200
Retry-After: 30

⚡ Fonctionnalités de Limitation de Taux SDK

Logique de Nouvelle Tentative Automatique

• Backoff exponentiel : Commence à 1 seconde, double à chaque tentative
• Nouvelles tentatives maximum : 3 tentatives avec intervalles de nouvelle tentative intelligents
• Jitter : Délais aléatoires pour éviter les effets de troupeau

File d'Attente de Requêtes

• Batching intelligent : Groupe plusieurs requêtes quand possible
• Gestion des priorités : Les opérations critiques obtiennent une priorité plus élevée
• Efficacité mémoire : Surcharge mémoire minimale pour les requêtes en file d'attente

Surveillance & Métriques

• Avertissements de limite de taux : Notifications proactives quand on approche des limites
• Timing des requêtes : Ajustement automatique basé sur l'usage actuel
• Suivi d'erreurs : Journalisation détaillée des rencontres de limites de taux

💡 Meilleures Pratiques avec les SDK

Opérations à Haut Volume

CLI C#

# Pour les opérations en masse, utilisez les commandes batch intégrées
sharokey bulk-create secrets.json --batch-size 20
# Gère automatiquement la limitation de taux

# Surveillez le progrès avec une sortie verbeuse
sharokey create "content" --verbose
# Montre le statut de limitation de taux et les tentatives de nouvelle tentative

JavaScript SDK

// Utilisez les opérations batch intégrées pour plusieurs secrets
const secretsData = [/* ... */];
const results = await client.createSecretsBatch(secretsData, {
  batchSize: 20,        // Le SDK optimise automatiquement
  maxConcurrency: 5     // Limite de requêtes concurrentes
});

// Activez la journalisation détaillée pour le dépannage
const client = new SharokeyClient({ 
  token: 'your_token',
  debug: true  // Montre la gestion des limites de taux dans les logs
});

Python SDK

# Opérations en masse asynchrones avec limitation de taux automatique
secrets_data = [/* ... */]
results = await client.create_bulk(secrets_data, 
  batch_size=20,           # Optimisation automatique
  max_concurrency=5        # Évite de surcharger l'API
)

# Surveillez le statut de limitation de taux
client.enable_rate_limit_logging()  # Logs détaillés de limitation de taux
stats = await client.get_rate_limit_status()
print(f"Requêtes restantes : {stats.remaining}")

Gestion d'Erreurs

Tous les SDK fournissent une gestion d'erreurs structurée pour les scénarios de limitation de taux :

// Gestion d'erreurs JavaScript SDK
try {
  const secret = await client.createSecret("content", options);
} catch (error) {
  if (error instanceof sharokey.RateLimitError) {
    console.log(`Limité par le taux, réessayer après : ${error.retryAfter}s`);
    // Le SDK a déjà réessayé automatiquement, ceci est l'échec final
  }
}

Options de Configuration

// Configurer le comportement de limitation de taux
const client = new SharokeyClient({
  token: 'your_token',
  rateLimiting: {
    maxRetries: 5,           // Défaut : 3
    baseDelay: 2000,         // Défaut : 1000ms
    maxDelay: 30000,         // Défaut : 16000ms
    enableJitter: true       // Défaut : true
  }
});

📊 Surveillance des Limites de Taux

Statut des Limites de Taux SDK

CLI C#

# Vérifier le statut actuel des limites de taux
sharokey status --rate-limits
# Montre : requêtes restantes, temps de réinitialisation, limites actuelles

JavaScript SDK

// Obtenir les informations actuelles de limite de taux
const status = await client.getRateLimitStatus();
console.log(`Restantes : ${status.remaining}/${status.limit}`);
console.log(`Se remet à : ${status.resetAt}`);

Python SDK

# Surveiller l'usage de limite de taux
status = await client.get_rate_limit_status()
print(f"Restantes : {status.remaining}/{status.limit}")
print(f"Se remet dans : {status.reset_in_seconds}s")

Optimisation des Performances

// Optimiser pour les scénarios à haut volume
const client = new SharokeyClient({
  token: 'your_token',
  requestQueue: {
    enabled: true,          // Activer la file d'attente de requêtes
    maxQueueSize: 1000,     // Mettre en file d'attente jusqu'à 1000 requêtes
    processingRate: 25      // Traiter 25 requêtes par minute
  }
});

// Utiliser le streaming pour de très grandes opérations
const stream = client.createSecretsStream(secretsData);
stream.on('created', (secret) => {
  console.log(`Créé : ${secret.slug}`);
});
stream.on('rateLimited', (delay) => {
  console.log(`Limité par le taux, attente ${delay}ms`);
});

🔗 Documentation Liée

• Gestion d'Erreurs - Référence complète de gestion d'erreurs
• Documentation CLI C# - Fonctionnalités de limitation de taux en ligne de commande
• JavaScript SDK - Limitation de taux navigateur et Node.js
• Python SDK - Patterns de limitation de taux asynchrones
• Authentification - Gestion et configuration des tokens

---

Tous les SDK implémentent une limitation de taux intelligente avec logique de nouvelle tentative automatique, file d'attente de requêtes et backoff exponentiel. Aucune gestion manuelle de limitation de taux requise.