Idempotency & conditional requests

Idempotency-Key: retry a write without doing it twice

Send an Idempotency-Key header (any string up to 200 characters, a UUID is fine) on any POST, PUT, PATCH or DELETE. For 24 hours, the same key with the same request replays the original response, marked Idempotent-Replay: true, without acting again. The same key with a different body is refused with 409 idempotency_key_reuse, which is the bug it exists to catch. Keys are scoped to your API key. 401, 429 and 5xx responses are never stored: they describe the moment, not the request.

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

Some writes are idempotent by construction and need no header: subscribing to an account you already monitor is a no-op that answers 200; DELETE of something you do not have is a no-op; setting the webhook to the URL it already has keeps the existing secret.

ETag and If-None-Match

Every JSON GET carries a weak ETag. Send it back as If-None-Match and an unchanged resource answers 304 with no body — cheap to check repeatedly.