Permintaan idempoten

Permintaan dapat gagal setelah Sursa sudah menyelesaikan pekerjaannya: koneksi terputus, atau proses Anda dimulai ulang sebelum respons tiba. Jika Anda mengirim POST yang sama lagi, Anda dapat membuat kartu kedua atau webhook kedua. Kunci idempotensi mencegah hal itu.

Kirim header Idempotency-Key bersama setiap POST dan PATCH. Jika Sursa sudah melihat permintaan dengan kunci ini, Sursa tidak menjalankan operasinya lagi: Sursa mengembalikan respons yang disimpannya pada kali pertama.

curl -X POST https://api.sursa.com/v1/cards/text \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Idempotency-Key: 6f1d2c9e-7b0a-4c43-9a51-0d6c1c1f8e21" \
  -H "Content-Type: application/json" \
  -d '{"title": "Refund policy", "body_markdown": "Refunds are processed within 14 days."}'

Permintaan yang diulang mendapat status dan isi yang sama dengan permintaan pertama, dengan satu header tambahan:

HTTP/1.1 200 OK
Idempotency-Replayed: true
X-Request-Id: 01JB7R…

Permintaan yang diulang memiliki X-Request-Id sendiri.

Memilih kunci

Pakai nilai acak baru, seperti UUID v4, untuk setiap operasi logis: “buat kartu ini”, “daftarkan webhook ini”. Pakai nilai yang sama untuk setiap percobaan ulang operasi itu, dan jangan pernah untuk operasi lain.
Kunci yang baik diturunkan dari data Anda sendiri jika ada, misalnya sync-2026-10-24-record-1042. Dengan begitu, bahkan job yang dimulai ulang dan kehilangan ingatannya mengirim kunci yang sama lagi.
Kunci terdiri atas 1 hingga 255 karakter ASCII yang dapat dicetak. Selain itu mengembalikan 400 dengan kode api.idempotency_key_invalid.

Apa yang dilakukan Sursa dengan kunci

Situasi	Respons
Permintaan pertama dengan kunci ini	Operasi berjalan seperti biasa.
Kunci sama, permintaan sama, permintaan pertama selesai dengan `2xx` atau `4xx`	Respons yang tersimpan, dengan `Idempotency-Replayed: true`. Operasi tidak dijalankan lagi.
Kunci sama, permintaan pertama masih berjalan	`409` `api.idempotency_in_progress` dengan `Retry-After: 1`. Tunggu, lalu coba lagi.
Kunci sama, tetapi metode, path, `Content-Type`, atau isinya berbeda	`409` `api.idempotency_mismatch`. Kunci sudah dipakai oleh permintaan lain.
Permintaan pertama selesai dengan `5xx` atau `429`	Kunci dilepas: permintaan berikutnya dengan kunci itu menjalankan operasinya lagi.

Kunci berlaku selama 24 jam. Setelah itu, kunci yang sama memulai operasi baru.
Kunci terpisah per organisasi dan per pemanggil: dua kunci API yang berbeda dapat memakai nilai yang sama tanpa saling memengaruhi.
Respons error dengan 4xx juga disimpan. Permintaan yang gagal validasi akan gagal dengan cara yang sama jika diulang dengan kunci yang sama; perbaiki permintaannya dan kirim dengan kunci baru.

Permintaan mana yang membutuhkannya

Metode	Idempotency-Key
`POST`, `PATCH`	Kirim header ini. Setiap endpoint yang menyimpan responsnya untuk pengulangan mencantumkan header tersebut di referensi API.
`GET`, `PUT`, `DELETE`	Tidak diperlukan: metode ini pada dasarnya aman untuk diulang. Header ini diterima dan tidak berpengaruh.
`POST` yang hanya membaca, seperti pencarian, laporan keuangan, dan `POST /v1/catalog/resolve`	Diterima, tetapi tidak ada yang disimpan: permintaan cukup dijalankan lagi.

Beberapa operasi aman untuk diulang bahkan tanpa header ini:

PUT /v1/cards-by-external-id/{external_id} membuat atau mengganti kartu dengan ID Anda; pengulangan dengan konten yang sama tidak mengubah apa pun.
Dokumen sumber kustom dikenali menurut external_id Anda; mengirim dokumen yang sama lagi mengembalikan unchanged.
Jawaban stream dari POST /v1/chat memakai field request_id di isi permintaan, bukan header. Lihat Membuat bot tanya jawab.

Mencoba ulang dengan aman

Gabungkan kunci dengan aturan percobaan ulang dari Error: buat kuncinya sekali, sebelum upaya pertama, dan kirim kunci itu bersama setiap upaya untuk operasi yang sama.