Idempotenz & bedingte Anfragen

Idempotency-Key: einen Schreibvorgang wiederholen, ohne ihn zweimal auszuführen

Senden Sie einen Idempotency-Key-Header (beliebige Zeichenkette bis 200 Zeichen, eine UUID ist in Ordnung) mit jedem POST, PUT, PATCH oder DELETE. 24 Stunden lang liefert derselbe Schlüssel mit derselben Anfrage die ursprüngliche Antwort erneut, markiert mit Idempotent-Replay: true, ohne erneut zu handeln. Derselbe Schlüssel mit einem anderen Body wird mit 409 idempotency_key_reuse abgewiesen – genau der Fehler, den er abfangen soll. Idempotenzschlüssel gelten je API-Schlüssel. 401-, 429- und 5xx-Antworten werden nie gespeichert: Sie beschreiben den Moment, nicht die Anfrage.

curl -X POST https://api.xsignalfeed.com/v1/keywords \
  -H "Authorization: Bearer xsf_your_key" -H "Idempotency-Key: 6f1c0c8e-add-solana" \
  -H "Content-Type: application/json" -d '{"query": "$SOL -filter:retweets"}'
# 201 the first time; the retry returns the same 201 body with Idempotent-Replay: true

Manche Schreibvorgänge sind von Natur aus idempotent und brauchen den Header nicht: Das Abonnieren eines bereits überwachten Kontos tut nichts und antwortet mit 200; DELETE von etwas, das Sie nicht haben, tut nichts; das Setzen des Webhooks auf die bereits eingetragene URL behält das bestehende Secret.

ETag und If-None-Match

Jedes JSON-GET trägt ein schwaches ETag. Senden Sie es als If-None-Match zurück, und eine unveränderte Ressource antwortet mit 304 ohne Body — günstig für wiederholte Prüfungen.