Idempotencia
Envía una cabecera Idempotency-Key con un POST y podrás reintentarlo tras un timeout sin crear lo mismo dos veces.
Por qué importa
Cuando una petición para crear algo da timeout, no sabes si ha fallado o si solo se ha perdido la respuesta. Reintentarla a ciegas podría registrar la misma transacción dos veces. Una clave de idempotencia hace que el reintento sea seguro: la API recuerda la primera respuesta y la repite.
Cómo usarla
Genera un valor único para cada operación, por ejemplo un UUID, y envíalo como cabecera. Envía el mismo valor cuando reintentes esa operación:
curl -X POST https://whisper.money/api/v1/transactions \
-H "Authorization: Bearer $WHISPER_MONEY_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 9b2f4c1e-5d3a-4e7b-8c6d-0a1b2c3d4e5f" \
-d '{
"account_id": "0199a3f4-1d2e-7c3b-8a4f-5e6d7c8b9a01",
"description": "Café",
"amount": -250,
"transaction_date": "2026-01-31"
}'
La cabecera es opcional, funciona en cualquier POST y se ignora en los demás
métodos. PATCH y PUT ya se pueden repetir sin riesgo, y repetir un DELETE solo
responde 404 la segunda vez.
Qué pasa al reintentar
- La primera petición fue bien. La API devuelve el mismo estado y el mismo
cuerpo sin volver a ejecutar la petición, con la cabecera
Idempotent-Replayed: true. Las claves se recuerdan durante 24 horas. - La primera petición sigue en curso. La API responde
409con el códigoidempotency_conflict. Espera un momento y reintenta. - La primera petición falló. Los errores no se recuerdan, así que el reintento se ejecuta de nuevo. Puedes corregir el cuerpo y reenviarlo con la misma clave.
- Misma clave, otra petición. Reutilizar una clave con otra ruta u otro
cuerpo responde
422, con el error enIdempotency-Key.
Las claves son tuyas: otro usuario que envíe el mismo valor no choca con el tuyo.
Una clave debe tener entre 1 y 255 caracteres; cualquier otra cosa responde
400 con el código invalid_idempotency_key.