Saltar al contenido
CA ES
Solicitar una demo

Desarrolladores

Idempotencia

Reintentos seguros con la cabecera Idempotency-Key: duración, comportamiento y conflictos.

Una red inestable puede dejarte sin saber si una petición llegó a procesarse. Si reintentas un POST /bookings sin más, podrías crear dos reservas. La cabecera Idempotency-Key te permite reintentar con seguridad.

Cómo se usa

Genera una clave única por intención (un UUID por reserva que quieres crear) y envíala en la cabecera:

curl -s -X POST "$PRANARP_URL/api/v1/bookings" \
  -H "Authorization: Bearer $PCK_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f1c9a5e-6c1b-4d57-9a2e-0e6f7d3a8b11" \
  -d '{
    "space_id": 7,
    "starts_at": "2026-10-22T18:00:00+02:00",
    "ends_at": "2026-10-22T19:00:00+02:00",
    "external_ref": "pedido-9981",
    "holder": { "name": "Laura Pons", "email": "laura@example.com" },
    "price": { "amount_cents": 2400, "paid_externally": true }
  }'

La cabecera es opcional, pero muy recomendable en POST /bookings, que es la única operación que la admite. El resto de operaciones de escritura (PUT y DELETE de jugadores, PATCH y DELETE de reservas) ya se pueden repetir sin efectos añadidos.

Qué ocurre al repetir la petición

Situación Resultado
Misma clave y mismo cuerpo, la original terminó bien (2xx) Se devuelve la respuesta guardada, con el mismo estado y cuerpo y la cabecera Idempotent-Replayed: true. No se crea nada nuevo.
Misma clave pero cuerpo distinto 409 idempotency_conflict.
Misma clave mientras la petición original sigue en curso 409 idempotency_conflict. Espera un momento y reintenta.
Clave de más de 255 caracteres o vacía 422 validation_failed.

Detalles a tener en cuenta:

  • Alcance: las claves son por credencial. Dos credenciales distintas pueden usar la misma clave sin interferir.
  • Duración: la clave y su respuesta se conservan 24 horas. Pasado ese tiempo, la clave puede reutilizarse.
  • Solo se guardan las respuestas correctas (2xx). Si la original falló (por ejemplo 409 slot_unavailable o 422), la clave se libera y puedes reintentar con la misma clave, idealmente tras corregir la causa.
  • Peticiones abandonadas: una clave que lleva más de 60 segundos «en curso» sin respuesta se considera abandonada y puede reutilizarse.
  • Al comparar cuerpos no importa el orden de las propiedades del JSON.

Buenas prácticas

  1. Guarda la clave junto con la intención en tu sistema antes de enviar la petición, para reutilizarla si hay que reintentar.
  2. Reintenta con la misma clave ante errores de red, 5xx y 429 (respeta Retry-After; ver límites de ritmo).
  3. Si recibes 409 idempotency_conflict, no cambies el cuerpo con la misma clave: usa una clave nueva si realmente quieres otra reserva.
  4. Si la respuesta incluye Idempotent-Replayed: true, trátala como éxito: la reserva ya existía.