Rate limits

L’API Samsa protège la capacité partagée avec deux limites indépendantes : un rate de requêtes par clé et un plafond de jobs concurrents par organisation. Les deux renvoient 429 avec des headers qui te disent quand réessayer.

Ces limites sont des valeurs par défaut et sont susceptibles de changer. Si ton intégration a besoin d’un plafond plus élevé, contacte support@samsa.ai.

Rate de requêtes par clé

Chaque API key peut effectuer jusqu’à 60 requêtes par minute, mesurées comme une fenêtre glissante de 60 secondes. Dépasser cette limite renvoie 429 avec code: "rate_limited". Les réponses réussies et les 429 de rate limit portent l’état actuel de la fenêtre (le header Retry-After n’est ajouté que sur les 429) :

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 41
X-RateLimit-Reset: 1782043260

Header	Signification
`X-RateLimit-Limit`	Requêtes autorisées par fenêtre (par défaut `60`).
`X-RateLimit-Remaining`	Requêtes restantes dans la fenêtre actuelle.
`X-RateLimit-Reset`	Timestamp Unix (en secondes) auquel la fenêtre se réinitialise.
`Retry-After`	Secondes à attendre avant de réessayer. Envoyé uniquement sur les réponses `429`.

Lis X-RateLimit-Remaining sur les réponses réussies pour ralentir avant d’atteindre la limite.

Plafond de concurrence par organisation

Indépendamment du rate de requêtes, une organisation peut avoir au plus 5 jobs concurrents en cours — jobs de génération, d’édition, de vidéo et de création de modèles encore pending ou processing, comptés sur toutes les clés de l’organisation. Soumettre un autre job alors qu’on est au plafond renvoie 429 avec code: "too_many_active_jobs" et un header Retry-After :

429 Too Many Requests

{
  "error": {
    "type": "rate_limit_error",
    "code": "too_many_active_jobs",
    "message": "Too many active jobs for this organization (5/5). Wait for in-flight jobs to finish before submitting more.",
    "request_id": "req_801c9a3b7d2d5f4a"
  }
}

Ce plafond protège la capacité de traitement, il est donc rattaché à toute l’organisation, pas à une clé unique. Attends que les jobs en cours atteignent un statut terminal — interroge leur endpoint GET, ou abonne-toi à un webhook — avant d’en soumettre d’autres.

Un exemple de 429

Un 429 de la fenêtre par clé inclut à la fois les headers Retry-After et X-RateLimit-* :

HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1782043260
Content-Type: application/json

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "API rate limit exceeded. Slow down and retry after the rate-limit window resets.",
    "request_id": "req_5f4a801c9a3b7d2d"
  }
}

Gérer les 429

Respecte Retry-After

Quand un 429 inclut un header Retry-After, attends au moins ce nombre de secondes avant de réessayer. C’est le signal qui fait autorité.

Ralentis de façon exponentielle

Pour des 429 répétés, augmente le délai entre les tentatives (par exemple 1s, 2s, 4s, 8s…), plafonné à un maximum raisonnable, avec un peu de jitter aléatoire pour éviter les réessais en troupeau (thundering herd).

Reste sous la limite de façon proactive

Surveille X-RateLimit-Remaining et throttle côté client avant d’atteindre 0. Pour le plafond de concurrence, borne le nombre de jobs que tu gardes en cours à la fois.

Voici une boucle de réessai minimale qui respecte Retry-After et retombe sur un backoff exponentiel.

import time
import requests


def request_with_retry(method, url, *, headers, max_retries=5, **kwargs):
    for attempt in range(max_retries + 1):
        resp = requests.request(method, url, headers=headers, **kwargs)
        if resp.status_code != 429 or attempt == max_retries:
            return resp
        retry_after = resp.headers.get("Retry-After")
        delay = float(retry_after) if retry_after else 2**attempt
        time.sleep(delay)
    return resp

async function requestWithRetry(
  url: string,
  init: RequestInit,
  maxRetries = 5,
): Promise<Response> {
  for (let attempt = 0; ; attempt++) {
    const resp = await fetch(url, init);
    if (resp.status !== 429 || attempt === maxRetries) return resp;
    const retryAfter = resp.headers.get("Retry-After");
    const delayMs = retryAfter ? Number(retryAfter) * 1000 : 2 ** attempt * 1000;
    await new Promise((r) => setTimeout(r, delayMs));
  }
}

Protection externe par IP

Au-delà de ces limites par clé et par organisation, Samsa applique une couche de protection par IP grossière à la périphérie du réseau (partagée avec le reste de la plateforme). C’est un garde-fou contre le trafic abusif, pas une limite que tu règles par intégration — les clients server-side bien élevés qui respectent les limites ci-dessus ne la rencontreront pas. Si tu routes de nombreuses organisations à travers une seule IP de sortie et que tu observes un throttling inattendu, contacte support@samsa.ai.

Prise en main

APIs

Vérification de contenu

Rate de requêtes par clé

Plafond de concurrence par organisation

Un exemple de 429

Gérer les 429

Protection externe par IP

​Rate de requêtes par clé

​Plafond de concurrence par organisation

​Un exemple de 429

​Gérer les 429

​Protection externe par IP

Rate de requêtes par clé

Plafond de concurrence par organisation

Un exemple de 429

Gérer les 429

Protection externe par IP