幂等性 & 条件请求

Idempotency-Key：重试写操作而不执行两次

在任何 POST、PUT、PATCH 或 DELETE 上发送 Idempotency-Key 头部（最长 200 个字符的任意字符串，UUID 即可）。24 小时内，相同的键配相同的请求会重放原始响应，并标记 Idempotent-Replay: true，不会再次执行。相同的键配不同的请求体会被拒绝，返回 409 idempotency_key_reuse——这正是它要捕获的 bug。键的作用域限于你的 API 密钥。401、429 和 5xx 响应从不存储：它们描述的是那一刻，而不是那个请求。

同一调用发两次——第二次不会重复执行

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

有些写操作天然幂等，不需要这个头：订阅你已在监控的账号是空操作，返回 200；DELETE 你没有的东西是空操作；把 Webhook 设为它已有的 URL 会保留现有密钥。

ETag 与 If-None-Match

每个 JSON GET 都带弱 ETag。把它作为 If-None-Match 发回，资源未变化时返回无正文的 304，适合反复廉价检查。