Idempotência & requisições condicionais

Idempotency-Key: repita uma escrita sem executá-la duas vezes

Envie um cabeçalho Idempotency-Key (qualquer string de até 200 caracteres; um UUID serve) em qualquer POST, PUT, PATCH ou DELETE. Por 24 horas, a mesma chave com a mesma requisição repete a resposta original, marcada com Idempotent-Replay: true, sem agir de novo. A mesma chave com um corpo diferente é recusada com 409 idempotency_key_reuse, que é exatamente o bug que ela existe para capturar. As chaves têm escopo da sua chave de API. Respostas 401, 429 e 5xx nunca são armazenadas: elas descrevem o momento, não a requisição.

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

Algumas escritas são idempotentes por construção e dispensam o cabeçalho: assinar uma conta que você já monitora não faz nada e responde 200; o DELETE de algo que você não tem não faz nada; definir o webhook para a URL que ele já tem mantém o segredo existente.

ETag e If-None-Match

Todo GET JSON carrega um ETag fraco. Envie-o de volta como If-None-Match e um recurso inalterado responde 304 sem corpo: barato de verificar repetidamente.