Idempotencja

Sieć zawodzi. Gdy żądanie utworzenia rezerwacji przerwie się bez odpowiedzi, nie wiesz, czy rezerwacja powstała. Nagłówek Idempotency-Key pozwala bezpiecznie je ponowić: to samo żądanie z tym samym kluczem wykona się najwyżej raz.

Gdzie jest wymagany

Endpoint	Idempotency-Key
POST /v1/bookings	wymagany
POST /v1/bookings/{booking_id}/payment	wymagany
POST /v1/bookings/{booking_id}/cancel	opcjonalny

Bez nagłówka — albo z pustym czy dłuższym niż 255 znaków — wymagane endpointy odpowiadają 422 idempotency_key_required. Anulowanie bez klucza wykonuje się bez idempotencji. Anulowanie rezerwacji już anulowanej i tak kończy się sukcesem.

Jak wybrać klucz

• Klucz ma od 1 do 255 znaków. Najprościej: UUID v4.
• Jeden klucz = jedna operacja biznesowa. Generuj go raz, zanim wyślesz pierwsze żądanie, i zapisz razem z operacją.
• Każde ponowienie tej operacji wysyłaj z tym samym kluczem i tym samym body.
• Nowa operacja — nowa rezerwacja, nowa sesja płatności — dostaje nowy klucz.

Klucze są osobne dla każdego klucza API. Ten sam Idempotency-Key wysłany innym kluczem API to inna operacja.

curl https://api.rezeri.com/v1/bookings \
  -H "Authorization: Bearer $REZERI_API_KEY" \
  -H "Idempotency-Key: 5d1f6a2e-8c3b-4f7a-9e21-0b6c4d8a7f13" \
  -H "Content-Type: application/json" \
  -d @booking.json

Co się dzieje przy powtórce

Żądanie porównujemy po metodzie, ścieżce i body.

Sytuacja	Odpowiedź
Pierwsze żądanie zakończyło się sukcesem (2xx)	Zapisana odpowiedź: ten sam status i body, z nagłówkiem Idempotent-Replayed: true. Nic nie wykonuje się ponownie.
Ten sam klucz, inne żądanie	422 idempotency_key_reused
Pierwsze żądanie wciąż trwa	409 idempotency_in_progress — ponów za chwilę z tym samym kluczem.
Pierwsze żądanie przerwało się po zapisie, wynik nieznany	409 idempotency_outcome_unknown — patrz niżej.
Pierwsze żądanie skończyło się odpowiedzią z błędem (4xx, 5xx)	Klucz jest zwalniany, a powtórka wykonuje się od nowa. Błędów nie zapisujemy.
Magazyn idempotencji niedostępny	503 idempotency_unavailable — nic się nie wykonało; ponów za chwilę z tym samym kluczem.

Zapisaną odpowiedź przechowujemy przez 24 godziny. Potem ten sam klucz wykona operację od nowa.

Powtórka zużywa limit żądań tak samo jak pierwsze żądanie.

Wynik nieznany

409 idempotency_outcome_unknown oznacza, że pierwsze żądanie przerwało się po tym, jak rezerwacja, sesja płatności albo anulowanie mogły już zostać zapisane. Ten klucz przez 24 godziny nie wykona zapisu ponownie.

1. Sprawdź stan przez GET /v1/bookings albo GET /v1/bookings/{booking_id}. Pomaga własny identyfikator zamówienia w metadata rezerwacji — metadata wraca w każdej odpowiedzi z rezerwacją.
2. Jeśli operacja się nie wykonała, ponów ją z nowym kluczem.

Sesja płatności przy powtórce

Powtórka POST /v1/bookings/{booking_id}/payment zwraca zapisaną sesję — także wtedy, gdy ta już wygasła (expires_at). Po wygaśnięciu wyślij żądanie z nowym kluczem: otworzy świeżą sesję.

Granica ochrony

W rzadkiej awarii magazynu przy zapisie odpowiedzi klient dostaje wynik, ale klucz pozostaje „w trakcie” przez 5 minut. Po tym czasie ponowienie z tym samym kluczem może wykonać operację drugi raz. Jeśli ponawiasz po dłuższej przerwie, najpierw sprawdź stan przez GET /v1/bookings.