Rate Limits

Die Samsa API schützt gemeinsam genutzte Kapazität mit zwei unabhängigen Limits: einer Request-Rate pro Key und einem Concurrency-Cap für Jobs pro Organisation. Beide geben 429 mit Headern zurück, die dir sagen, wann du es erneut versuchen sollst.

Diese Limits sind Defaults und können sich ändern. Wenn deine Integration eine höhere Obergrenze braucht, kontaktiere support@samsa.ai.

Request-Rate pro Key

Jeder API key darf bis zu 60 Requests pro Minute machen, gemessen als gleitendes 60-Sekunden-Fenster. Ein Überschreiten gibt 429 mit code: "rate_limited" zurück. Erfolgreiche Antworten und Rate-Limit-429s tragen den aktuellen Fensterzustand (der Retry-After-Header wird nur bei 429s hinzugefügt):

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

Header	Bedeutung
`X-RateLimit-Limit`	Erlaubte Requests pro Fenster (Default `60`).
`X-RateLimit-Remaining`	Verbleibende Requests im aktuellen Fenster.
`X-RateLimit-Reset`	Unix-Zeitstempel (Sekunden), wann das Fenster zurückgesetzt wird.
`Retry-After`	Zu wartende Sekunden vor dem erneuten Versuch. Nur bei `429`-Antworten gesendet.

Lies X-RateLimit-Remaining bei erfolgreichen Antworten, um langsamer zu werden, bevor du das Limit erreichst.

Concurrency-Cap pro Organisation

Unabhängig von der Request-Rate darf eine Organisation höchstens 5 gleichzeitige laufende Jobs haben — Generierungs-, Edit-, Video- und Modellerstellungs-Jobs, die noch pending oder processing sind, gezählt über jeden Key der Organisation hinweg. Einen weiteren Job einzureichen, während der Cap erreicht ist, gibt 429 mit code: "too_many_active_jobs" und einem Retry-After-Header zurück:

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

Dieser Cap schützt die Verarbeitungskapazität, daher ist er an die gesamte Organisation gebunden, nicht an einen einzelnen Key. Warte, bis laufende Jobs einen terminalen Status erreichen — frage ihren GET-Endpoint ab oder abonniere einen Webhook — bevor du weitere einreichst.

Ein Beispiel-429

Ein 429 aus dem Fenster pro Key enthält sowohl den Retry-After- als auch die X-RateLimit-*-Header:

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

Mit 429ern umgehen

Halte Retry-After ein

Wenn ein 429 einen Retry-After-Header enthält, warte mindestens so viele Sekunden vor dem erneuten Versuch. Es ist das maßgebliche Signal.

Weiche exponentiell zurück

Erhöhe bei wiederholten 429s die Verzögerung zwischen den Versuchen (zum Beispiel 1s, 2s, 4s, 8s…), gedeckelt auf ein sinnvolles Maximum, mit ein wenig zufälligem Jitter, um Thundering-Herd-Retries zu vermeiden.

Bleib proaktiv unter dem Limit

Beobachte X-RateLimit-Remaining und drossle clientseitig, bevor du 0 erreichst. Begrenze für den Concurrency-Cap, wie viele Jobs du gleichzeitig laufen lässt.

Unten steht eine minimale Retry-Schleife, die Retry-After einhält und auf exponentielles Backoff zurückfällt.

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

Äußerer Schutz pro IP

Über diese Limits pro Key und pro Organisation hinaus wendet Samsa eine grobe Schutzschicht pro IP am Netzwerkrand an (geteilt mit dem Rest der Plattform). Sie ist ein Backstop gegen missbräuchlichen Traffic, kein Limit, das du pro Integration einstellst — gutartige serverseitige Clients, die die obigen Limits respektieren, werden ihr nicht begegnen. Wenn du viele Organisationen über eine einzelne Egress-IP leitest und unerwartetes Throttling siehst, kontaktiere support@samsa.ai.

Erste Schritte

APIs

Inhaltsverifizierung

Request-Rate pro Key

Concurrency-Cap pro Organisation

Ein Beispiel-429

Mit 429ern umgehen

Äußerer Schutz pro IP

​Request-Rate pro Key

​Concurrency-Cap pro Organisation

​Ein Beispiel-429

​Mit 429ern umgehen

​Äußerer Schutz pro IP

Request-Rate pro Key

Concurrency-Cap pro Organisation

Ein Beispiel-429

Mit 429ern umgehen

Äußerer Schutz pro IP