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

> Limiti di richieste per chiave, tetti di concorrenza per organizzazione, gli header da osservare e come fare back-off.

La Samsa API protegge la capacità condivisa con due limiti indipendenti: un **rate di
richieste per chiave** e un **tetto di job concorrenti per organizzazione**. Entrambi
restituiscono [`429`](/it/guides/errors#rate_limited) con header che ti dicono quando
riprovare.

<Info>
  Questi limiti sono valori predefiniti e sono **soggetti a modifica**. Se la tua
  integrazione necessita di un tetto più alto, contatta
  [support@samsa.ai](mailto:support@samsa.ai).
</Info>

## Rate di richieste per chiave

Ogni API key può fare fino a **60 richieste al minuto**, misurate come una finestra
scorrevole di 60 secondi. Superarlo restituisce `429` con `code: "rate_limited"`.

Le risposte andate a buon fine e i `429` di rate limit portano lo stato attuale della
finestra (l'header `Retry-After` viene aggiunto solo sui `429`):

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

| Header                  | Significato                                                                     |
| ----------------------- | ------------------------------------------------------------------------------- |
| `X-RateLimit-Limit`     | Richieste consentite per finestra (predefinito `60`).                           |
| `X-RateLimit-Remaining` | Richieste rimaste nella finestra attuale.                                       |
| `X-RateLimit-Reset`     | Timestamp Unix (secondi) di quando la finestra si resetta.                      |
| `Retry-After`           | Secondi da attendere prima di riprovare. **Inviato solo sulle risposte `429`.** |

Leggi `X-RateLimit-Remaining` sulle risposte andate a buon fine per rallentare *prima*
di raggiungere il limite.

## Tetto di concorrenza per organizzazione

Indipendentemente dal rate di richieste, un'organizzazione può avere al massimo **5
job concorrenti in corso** — job di generazione, modifica, video e creazione di
modelli ancora `pending` o `processing`, contati su ogni chiave dell'organizzazione.
Inviare un altro job mentre si è al tetto restituisce `429` con
`code: "too_many_active_jobs"` e 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"
  }
}
```

Questo tetto protegge la capacità di elaborazione, quindi è legato all'intera
organizzazione, non a una singola chiave. Aspetta che i job in corso raggiungano uno
stato terminale — interroga il loro endpoint `GET` o iscriviti a un
[webhook](/it/guides/webhooks) — prima di inviarne altri.

## Un esempio di 429

Un `429` dalla finestra per chiave include sia gli header `Retry-After` che
`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"
  }
}
```

## Gestire i 429

<Steps>
  <Step title="Rispetta Retry-After">
    Quando un `429` include un header `Retry-After`, aspetta almeno quel numero di
    secondi prima di riprovare. È il segnale autoritativo.
  </Step>

  <Step title="Fai back-off esponenziale">
    Per `429` ripetuti, aumenta il ritardo tra i tentativi (per esempio
    1s, 2s, 4s, 8s…), limitato a un massimo sensato, con un po' di jitter casuale per
    evitare i retry a valanga.
  </Step>

  <Step title="Resta sotto il limite in modo proattivo">
    Osserva `X-RateLimit-Remaining` e throttla lato client prima di raggiungere `0`.
    Per il tetto di concorrenza, limita quanti job mantieni in corso alla volta.
  </Step>
</Steps>

Qui sotto c'è un loop di retry minimale che rispetta `Retry-After` e ripiega su un
backoff esponenziale.

<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>

## Protezione esterna per IP

Oltre a questi limiti per chiave e per organizzazione, Samsa applica un livello di
protezione **per IP** grossolano al confine di rete (condiviso con il resto della
piattaforma). È un backstop contro il traffico abusivo, non un limite che regoli per
integrazione — i client server-side ben educati che rispettano i limiti qui sopra non
lo incontreranno. Se instradi molte organizzazioni attraverso un singolo IP di uscita
e vedi un throttling inaspettato, contatta
[support@samsa.ai](mailto:support@samsa.ai).