Idempotencia & solicitudes condicionales

Idempotency-Key: reintenta una escritura sin hacerla dos veces

Envía una cabecera Idempotency-Key (cualquier cadena de hasta 200 caracteres; un UUID sirve) en cualquier POST, PUT, PATCH o DELETE. Durante 24 horas, la misma clave con la misma solicitud repite la respuesta original, marcada con Idempotent-Replay: true, sin actuar de nuevo. La misma clave con un cuerpo distinto se rechaza con 409 idempotency_key_reuse, que es justo el error que existe para detectar. Las claves están acotadas a tu clave de API. Las respuestas 401, 429 y 5xx nunca se almacenan: describen el momento, no la solicitud.

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

Algunas escrituras son idempotentes por construcción y no necesitan la cabecera: suscribirse a una cuenta que ya monitorizas no hace nada y responde 200; el DELETE de algo que no tienes no hace nada; fijar el webhook en la URL que ya tiene conserva el secreto existente.

ETag e If-None-Match

Cada GET JSON lleva un ETag débil. Devuélvelo como If-None-Match y un recurso sin cambios responde 304 sin cuerpo: barato de comprobar repetidamente.