Rate limits

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 con header che ti dicono quando riprovare.

Questi limiti sono valori predefiniti e sono soggetti a modifica. Se la tua integrazione necessita di un tetto più alto, contatta support@samsa.ai.

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:

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

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 — prima di inviarne altri.

Un esempio di 429

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

Gestire i 429

Rispetta Retry-After

Quando un 429 include un header Retry-After, aspetta almeno quel numero di secondi prima di riprovare. È il segnale autoritativo.

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.

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.

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

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));
  }
}

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.

Per iniziare

API

Verifica dei contenuti

Rate di richieste per chiave

Tetto di concorrenza per organizzazione

Un esempio di 429

Gestire i 429

Protezione esterna per IP

​Rate di richieste per chiave

​Tetto di concorrenza per organizzazione

​Un esempio di 429

​Gestire i 429

​Protezione esterna per IP

Rate di richieste per chiave

Tetto di concorrenza per organizzazione

Un esempio di 429

Gestire i 429

Protezione esterna per IP