Grundlagen

Idempotenz & Limits

Ein Header verhindert den doppelten Versand. Zwei weitere sagen, wie schnell Sie arbeiten dürfen.

Idempotency-Key

Jeder schreibende Aufruf — POST, PUT, PATCH, DELETE — akzeptiert Idempotency-Key. Es gibt nichts pro Route zu aktivieren.

Der Grund ist nicht Bequemlichkeit. Eine Verbindung kann abbrechen, nachdem der Server geschrieben hat und bevor die Antwort ankommt — und kein Client kann diesen Fall von einer Anfrage unterscheiden, die nie angekommen ist. Ohne Schlüssel ist ein Wiederholungsversuch auf /send eine zweite Kopie derselben Vereinbarung in einem fremden Postfach.

Gleicher Schlüssel, gleicher Body: Die gespeicherte Antwort wird wortgleich wiederholt und der Handler läuft nicht erneut. Die Antwort trägt Idempotency-Replayed: true.
Gleicher Schlüssel, anderer Body: 422 IDEMPOTENCY_KEY_REUSED. Ein stilles Wiederholen würde die falsche Frage beantworten.
Gleicher Schlüssel, noch laufend: 409 IDEMPOTENCY_IN_PROGRESS. Zwei parallele Antworten wären genau der Doppelversand, den der Header verhindern soll. Kurz warten und erneut versuchen.
Format: 8 bis 255 Zeichen aus [A-Za-z0-9_.:-], beginnend mit einem Buchstaben oder einer Ziffer. Eine UUID passt.
Geltungsdauer: 24 Stunden, danach ist der Schlüssel wieder frei — auch für einen anderen Body.
Geltungsbereich: Organisation + Schlüssel + Endpunkt. Zwei Organisationen dürfen dieselbe UUID wählen, und derselbe Schlüssel auf zwei verschiedenen Endpunkten sind zwei Vorgänge.

POST /signature-requests/{id}/send

curl "https://api.signido.de/api/v1/signature-requests/$REQ_ID/send" \
  -H "Authorization: Bearer $SIGNIDO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: auftrag-4711" \
  -d '{}'

# Derselbe Aufruf noch einmal: dieselbe Antwort, kein zweiter Versand.
# Der Header Idempotency-Replayed: true sagt, dass nichts erneut lief.

Rate Limits

Gezählt wird pro API-Schlüssel und pro Organisation, in einem gleitenden Fenster — nicht in festen Minuten. Ein festes Fenster erlaubt ein vollständiges Budget um 12:00:59 und ein zweites um 12:01:00, also den doppelten Wert über zwei Sekunden.

X-RateLimit-Limit: Anfragen, die im aktuellen Fenster erlaubt sind.
X-RateLimit-Remaining: Was davon übrig ist. Beide Header stehen auf jeder Antwort.
Retry-After: Nur bei 429: Sekunden, nach denen ein erneuter Versuch zulässig ist. Diesen Wert abwarten, statt eine eigene Wartezeit zu schätzen — der Server weiß, wann das Fenster öffnet.

Die Grenzen unterscheiden sich pro Route und stehen an jeder Operation in der Referenz. Routen, die Mail oder eine SMS versenden, sind enger begrenzt und lehnen bei einer Störung des Zählers ab, statt ein unbegrenztes Volumen durchzulassen: die ehrliche Antwort auf „noch einmal anstoßen“ ist dann „nicht jetzt“. Der Versand selbst ist absichtlich nicht so konfiguriert — Vereinbarungen nicht mehr verschicken zu können, weil ein Cache nicht erreichbar ist, würde die Kernfunktion des Produkts an einer Störung aufhängen, die nichts damit zu tun hat.