İdempotent istekler

Bir istek, Sursa işi zaten yapmışken başarısız olabilir: bağlantı kopar ya da yanıt gelmeden önce süreciniz yeniden başlar. Aynı POST isteğini yeniden gönderirseniz ikinci bir kart ya da ikinci bir webhook oluşturabilirsiniz. Bunu bir idempotency anahtarı önler: aynı isteğin tekrarı işlemi ikinci kez çalıştırmaz.

Her POST ve PATCH isteğiyle bir Idempotency-Key başlığı gönderin. Sursa bu anahtarı taşıyan bir isteği daha önce aldıysa işlemi yeniden çalıştırmaz: ilk seferde kaydettiği yanıtı döndürür.

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."}'

Tekrarlanan istek, ilkiyle aynı durumu ve gövdeyi ek bir başlıkla birlikte alır:

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

Tekrarlanan isteğin kendi X-Request-Id değeri vardır.

Anahtar seçme

Her mantıksal işlem için UUID v4 gibi yeni ve rastgele bir değer kullanın: “bu kartı oluştur”, “bu webhook’u kaydet”. Aynı değeri bu işlemin her yeniden denemesinde kullanın, farklı bir işlem için hiçbir zaman kullanmayın.
Elinizde kendi verileriniz varsa iyi bir anahtar bunlardan türetilir, örneğin sync-2026-10-24-record-1042. Böylece belleğini kaybetmiş, yeniden başlatılmış bir iş bile aynı anahtarı yeniden gönderir.
Anahtar 1–255 yazdırılabilir ASCII karakterden oluşur. Başka her değer api.idempotency_key_invalid koduyla 400 döndürür.

Sursa’nın anahtarla yaptıkları

Durum	Yanıt
Bu anahtarla gelen ilk istek	İşlem her zamanki gibi çalışır.
Aynı anahtar, aynı istek; ilki `2xx` ya da `4xx` ile tamamlandı	Kaydedilmiş yanıt, `Idempotency-Replayed: true` başlığıyla. İşlem yeniden çalışmaz.
Aynı anahtar; ilk istek hâlâ çalışıyor	`409` `api.idempotency_in_progress`, `Retry-After: 1` başlığıyla. Bekleyin ve yeniden deneyin.
Aynı anahtar; farklı yöntem, yol, `Content-Type` ya da gövde	`409` `api.idempotency_mismatch`. Anahtar zaten başka bir istek tarafından kullanılıyor.
İlk istek `5xx` ya da `429` ile tamamlandı	Anahtar serbest bırakılır: bu anahtarla gelen sonraki istek işlemi yeniden çalıştırır.

Bir anahtar 24 saat geçerlidir. Bu süreden sonra aynı anahtar yeni bir işlem başlatır.
Anahtarlar her kuruluş ve her çağıran için ayrıdır: iki farklı API anahtarı birbirini etkilemeden aynı değeri kullanabilir.
4xx ile biten hata yanıtları da kaydedilir. Geçerlilik denetiminden geçemeyen bir istek, aynı anahtarla tekrarlandığında aynı şekilde başarısız olur; isteği düzeltin ve yeni bir anahtarla gönderin.

Hangi istekler anahtar gerektirir

Yöntem	Idempotency-Key
`POST`, `PATCH`	Gönderin. Yanıtını tekrar için saklayan her uç nokta, API başvurusunda başlığı listeler.
`GET`, `PUT`, `DELETE`	Gerekmez: bu yöntemler anlamları gereği güvenle tekrarlanabilir. Başlık kabul edilir ve hiçbir etkisi yoktur.
Arama, finansal raporlar ve `POST /v1/catalog/resolve` gibi yalnızca okuma yapan `POST`	Kabul edilir, ancak hiçbir şey kaydedilmez: istek yalnızca yeniden çalışır.

Bazı işlemler başlık olmadan da güvenle tekrarlanabilir:

PUT /v1/cards-by-external-id/{external_id} kartı sizin kimliğinizle oluşturur ya da değiştirir; aynı içerikle yapılan tekrar hiçbir şeyi değiştirmez.
Özel kaynak belgeleri sizin external_id değerinizle anahtarlanır; aynı belgeyi yeniden göndermek unchanged döndürür.
POST /v1/chat isteğinin akış hâlindeki yanıtı, başlık yerine gövdedeki request_id alanını kullanır. Soru-cevap botu oluşturma sayfasına bakın.

Güvenli yeniden deneme

Anahtarı Hatalar sayfasındaki yeniden deneme kurallarıyla birlikte kullanın: anahtarı ilk denemeden önce bir kez oluşturun ve aynı işlemin her denemesinde gönderin.