> ## Documentation Index
> Fetch the complete documentation index at: https://docs.samsa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limits

> Limites de requêtes par clé, plafonds de concurrence par organisation, les headers à surveiller et comment ralentir.

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`](/fr/guides/errors#rate_limited) avec des
headers qui te disent quand réessayer.

<Info>
  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](mailto:support@samsa.ai).
</Info>

## 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` :

```json 429 Too Many Requests theme={null}
{
  "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](/fr/guides/webhooks) — 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 theme={null}
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

<Steps>
  <Step title="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é.
  </Step>

  <Step title="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).
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

<CodeGroup>
  ```python Python theme={null}
  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
  ```

  ```typescript TypeScript theme={null}
  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));
    }
  }
  ```
</CodeGroup>

## 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](mailto:support@samsa.ai).