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

> Request-Limits pro Key, Concurrency-Caps pro Organisation, die zu beobachtenden Header und wie du zurückweichst.

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`](/de/guides/errors#rate_limited) mit Headern
zurück, die dir sagen, wann du es erneut versuchen sollst.

<Info>
  Diese Limits sind Defaults und **können sich ändern**. Wenn deine Integration
  eine höhere Obergrenze braucht, kontaktiere
  [support@samsa.ai](mailto:support@samsa.ai).
</Info>

## 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-`429`s tragen den aktuellen Fensterzustand
(der `Retry-After`-Header wird nur bei `429`s 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:

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

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](/de/guides/webhooks) — 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 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"
  }
}
```

## Mit 429ern umgehen

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

  <Step title="Weiche exponentiell zurück">
    Erhöhe bei wiederholten `429`s 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.
  </Step>

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

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

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

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