Salta al contingut
CA ES
Sol·licita una demo

Desenvolupadors

Idempotència

Reintents segurs amb la capçalera Idempotency-Key: durada, comportament i conflictes.

Una xarxa inestable pot deixar-te sense saber si una petició s'ha arribat a processar. Si reintentes un POST /bookings sense més, podries crear dues reserves. La capçalera Idempotency-Key et permet reintentar amb seguretat.

Com es fa servir

Genera una clau única per intenció (un UUID per cada reserva que vols crear) i envia-la a la capçalera:

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": "comanda-9981",
    "holder": { "name": "Laura Pons", "email": "laura@example.com" },
    "price": { "amount_cents": 2400, "paid_externally": true }
  }'

La capçalera és opcional, però molt recomanable a POST /bookings, que és l'única operació que l'admet. La resta d'operacions d'escriptura (PUT i DELETE de jugadors, PATCH i DELETE de reserves) ja es poden repetir sense efectes addicionals.

Què passa en repetir la petició

Situació Resultat
Mateixa clau i mateix cos, l'original ha acabat bé (2xx) Es retorna la resposta desada, amb el mateix estat i cos i la capçalera Idempotent-Replayed: true. No es crea res de nou.
Mateixa clau però cos diferent 409 idempotency_conflict.
Mateixa clau mentre la petició original encara és en curs 409 idempotency_conflict. Espera un moment i reintenta.
Clau de més de 255 caràcters o buida 422 validation_failed.

Detalls a tenir en compte:

  • Abast: les claus són per credencial. Dues credencials diferents poden fer servir la mateixa clau sense interferir.
  • Durada: la clau i la seva resposta es conserven 24 hores. Passat aquest temps, la clau es pot reutilitzar.
  • Només es desen les respostes correctes (2xx). Si l'original ha fallat (per exemple 409 slot_unavailable o 422), la clau s'allibera i pots reintentar amb la mateixa clau, idealment després de corregir-ne la causa.
  • Peticions abandonades: una clau que fa més de 60 segons que és «en curs» sense resposta es considera abandonada i es pot reutilitzar.
  • En comparar cossos no importa l'ordre de les propietats del JSON.

Bones pràctiques

  1. Desa la clau juntament amb la intenció al teu sistema abans d'enviar la petició, per reutilitzar-la si cal reintentar.
  2. Reintenta amb la mateixa clau davant d'errors de xarxa, 5xx i 429 (respecta Retry-After; vegeu límits de ritme).
  3. Si reps 409 idempotency_conflict, no canviïs el cos amb la mateixa clau: fes servir una clau nova si realment vols una altra reserva.
  4. Si la resposta inclou Idempotent-Replayed: true, tracta-la com un èxit: la reserva ja existia.