Gdy wystąpi błąd sieci lub upłynie limit czasu, ponowienie mutacji może przypadkowo wywołać zduplikowane skutki uboczne - na przykład dwukrotnie utworzyć ten sam element. Nagłówek Idempotency-Key pozwala bezpiecznie ponawiać mutacje bez obaw o duplikaty.

Jak to działa

Do każdego żądania mutacji dodaj unikatowy nagłówek Idempotency-Key. API używa tego klucza do eliminowania duplikatów przy ponowieniach:

1. Pierwsze żądanie: zostaje wykonane standardowo, a odpowiedź jest przechowywana w pamięci podręcznej przez 30 minut.
2. Ponowienie z tym samym kluczem: zwraca zapisaną odpowiedź z nagłówkiem Idempotency-Replayed: true - nie dochodzi do zduplikowanego skutku ubocznego.
3. Równoczesne zduplikowane żądanie: zwraca 409 Conflict z nagłówkiem Retry-After, który wskazuje, kiedy ponowić żądanie.

👍 Najlepsza praktyka

W środowisku produkcyjnym zawsze dodawaj nagłówek Idempotency-Key przy ponawianiu mutacji. Jest to szczególnie ważne w przypadku operacji takich jak create_item, create_board i innych mutacji tworzących lub modyfikujących zasoby.

Używanie nagłówka Idempotency-Key

Dodaj unikatową wartość tekstową (np. UUID) do nagłówka żądania Idempotency-Key:

fetch("https://api.monday.com/v2", {
  method: "post",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "{API_TOKEN}",
    "API-Version": "2025-07",
    "Idempotency-Key": "YOUR_UNIQUE_IDEMPOTENCY_KEY"
  },
  body: JSON.stringify({
    query: `mutation { create_item(board_id: 123456, item_name: "New item") { id } }`
  })
});

curl -X POST 'https://api.monday.com/v2' \
-H "Authorization: {API_TOKEN}" \
-H "Content-Type:application/json" \
-H "API-Version:2025-07" \
-H "Idempotency-Key:YOUR_UNIQUE_IDEMPOTENCY_KEY" \
--data-raw '{"query":"mutation { create_item(board_id: 123456, item_name: \"New item\") { id } }"}'

Nagłówki odpowiedzi

Nagłówek	Opis
Idempotency-Replayed	Przyjmuje wartość true, gdy odpowiedź pochodzi z pamięci podręcznej (czyli jest to odpowiedź z ponowionego żądania, a nie nowego wykonania).

Zasady i ograniczenia

Zasada	Szczegóły
Tylko mutacje	Nagłówek jest ignorowany w zapytaniach (odczyty są z natury idempotentne).
Tylko POST	Dotyczy wyłącznie żądań POST.
Czas przechowywania w pamięci podręcznej	Zapisane odpowiedzi wygasają po 30 minutach. Po tym czasie żądanie z tym samym kluczem zostanie wykonane ponownie.
Format klucza	Dowolny niepusty ciąg znaków. Zalecamy używanie UUID.
Limit pamięci na użytkownika	Dla każdej kombinacji użytkownika i aplikacji obowiązuje limit pamięci na zapisane odpowiedzi. Po jego przekroczeniu nowe odpowiedzi zostaną zwrócone, ale nie będą przechowywane w celu ponownego użycia.
Maksymalny rozmiar odpowiedzi	Odpowiedzi większe niż 1 MB nie są przechowywane w pamięci podręcznej.

Odpowiedzi błędów

409 - równoczesne zduplikowane żądanie

Jeśli żądanie z tym samym kluczem idempotencji jest już przetwarzane, API zwraca:

{
  "errors": [
    {
      "message": "A request with this idempotency key is currently being processed",
      "extensions": {
        "code": "IDEMPOTENCY_CONFLICT"
      }
    }
  ]
}

Odpowiedź zawiera nagłówek Retry-After. Poczekaj wskazany czas i ponów żądanie - zapisana odpowiedź będzie wtedy dostępna.

Kiedy używać kluczy idempotencji

Scenariusz	Użyć klucza idempotencji?
Ponowienie po przekroczeniu limitu czasu połączenia	✅ Tak
Ponowienie po błędzie serwera 5xx	✅ Tak
Ponowienie po przekroczeniu limitu liczby żądań (429)	❌ Nie - pierwotne żądanie nie zostało przetworzone, więc nie ma ryzyka duplikatu.
Mutacje uruchamiane automatycznie lub przez webhook	✅ Tak - utwórz klucz na podstawie identyfikatora zdarzenia wyzwalającego.
Importy wsadowe	✅ Tak - użyj osobnego klucza dla każdego rekordu, aby bezpiecznie wznowić import po częściowym niepowodzeniu.

Generowanie kluczy idempotencji

Dobre klucze są:

• Unikatowe dla każdej planowanej operacji - UUID wygenerowany przy pierwszej próbie i używany ponownie przy ponowieniach.
• Deterministyczne dla tej samej operacji - przy ponowieniu wysyłaj ten sam klucz, nie generuj nowego.

Przykłady:

• uuid() - wygenerowany raz po kliknięciu przez użytkownika przycisku „Utwórz” i używany ponownie przy ponowieniach.
• ${webhookEventId}-create-item - do automatyzacji uruchamianych przez webhook.
• ${importBatchId}-row-${rowIndex} - do importów wsadowych.

🚧 Ostrzeżenie

Nie generuj nowego klucza przy każdej próbie ponowienia. Aby eliminowanie duplikatów działało, klucz musi pozostać taki sam przy wszystkich ponowieniach. Zapisz go razem z żądaniem, aby ponowienia używały tej samej wartości.