คำขอที่ทำซ้ำได้อย่างปลอดภัย

คำขออาจล้มเหลวหลังจากที่ Sursa ทำงานเสร็จไปแล้ว เช่น การเชื่อมต่อขาด หรือโปรเซสของคุณรีสตาร์ตก่อนที่การตอบกลับจะมาถึง หากส่ง POST เดิมอีกครั้ง คุณอาจสร้างการ์ดใบที่สองหรือเว็บฮุกรายการที่สองขึ้นมา คีย์ป้องกันการทำซ้ำ (idempotency key) ช่วยป้องกันปัญหานี้

ส่งเฮดเดอร์ Idempotency-Key ไปกับทุกคำขอ POST และ PATCH หาก Sursa เคยได้รับคำขอที่ใช้คีย์นี้แล้ว Sursa จะไม่ทำการดำเนินการนั้นซ้ำ แต่จะส่งคืนการตอบกลับที่บันทึกไว้ในครั้งแรก

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

คำขอที่ส่งซ้ำจะได้สถานะและเนื้อหาเหมือนคำขอแรก พร้อมเฮดเดอร์เพิ่มเติม:

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

คำขอที่ส่งซ้ำมี X-Request-Id ของตัวเอง

การเลือกคีย์

ใช้ค่าสุ่มใหม่ เช่น UUID v4 สำหรับแต่ละ การดำเนินการเชิงตรรกะ เช่น “สร้างการ์ดใบนี้” หรือ “ลงทะเบียนเว็บฮุกนี้” ใช้ค่าเดียวกันในทุกการลองใหม่ของการดำเนินการนั้น และอย่าใช้กับการดำเนินการอื่นเด็ดขาด
คีย์ที่ดีสร้างจากข้อมูลของคุณเองเมื่อมีข้อมูลให้ใช้ เช่น sync-2026-10-24-record-1042 เมื่อเป็นเช่นนี้ แม้งานที่รีสตาร์ตและลืมสถานะเดิมไปแล้วก็ยังส่งคีย์เดิมอีกครั้ง
คีย์ประกอบด้วยอักขระ ASCII ที่พิมพ์ได้ 1–255 ตัว ค่าอื่นจะได้การตอบกลับ 400 พร้อมรหัส api.idempotency_key_invalid

สิ่งที่ Sursa ทำกับคีย์

สถานการณ์	การตอบกลับ
คำขอแรกที่ใช้คีย์นี้	การดำเนินการทำงานตามปกติ
คีย์เดิม คำขอเดิม และคำขอแรกจบด้วย `2xx` หรือ `4xx`	การตอบกลับที่บันทึกไว้พร้อม `Idempotency-Replayed: true` โดยไม่ทำการดำเนินการซ้ำ
คีย์เดิม และคำขอแรกยังทำงานอยู่	`409` `api.idempotency_in_progress` พร้อม `Retry-After: 1` ให้รอแล้วลองใหม่
คีย์เดิม แต่เมธอด พาธ `Content-Type` หรือเนื้อหาต่างกัน	`409` `api.idempotency_mismatch` คีย์นี้ถูกคำขออื่นใช้ไปแล้ว
คำขอแรกจบด้วย `5xx` หรือ `429`	ระบบปล่อยคีย์คืน คำขอถัดไปที่ใช้คีย์นี้จะทำการดำเนินการอีกครั้ง

คีย์ใช้ได้ 24 ชั่วโมง หลังจากนั้น คีย์เดิมจะเริ่มการดำเนินการใหม่
คีย์แยกกันตามองค์กรและตามผู้เรียก คีย์ API สองคีย์ที่ต่างกันใช้ค่าเดียวกันได้โดยไม่กระทบกัน
การตอบกลับที่เป็นข้อผิดพลาด 4xx ก็ถูกบันทึกไว้เช่นกัน คำขอที่ไม่ผ่านการตรวจความถูกต้องของข้อมูลจะล้มเหลวแบบเดิมเมื่อส่งซ้ำด้วยคีย์เดิม ให้แก้คำขอแล้วส่งด้วยคีย์ใหม่

คำขอที่ต้องใช้คีย์

เมธอด	Idempotency-Key
`POST` และ `PATCH`	ส่งคีย์ไปด้วย ทุกเอนด์พอยต์ที่บันทึกการตอบกลับไว้สำหรับการส่งซ้ำระบุเฮดเดอร์นี้ไว้ใน เอกสารอ้างอิง API
`GET` `PUT` และ `DELETE`	ไม่จำเป็น เพราะโดยความหมายแล้วเมธอดเหล่านี้ทำซ้ำได้อย่างปลอดภัย ระบบยอมรับเฮดเดอร์นี้แต่ไม่มีผลใด
`POST` ที่อ่านอย่างเดียว เช่น การค้นหา รายงานทางการเงิน และ `POST /v1/catalog/resolve`	ระบบยอมรับแต่ไม่บันทึกอะไร คำขอเพียงทำงานอีกครั้ง

การดำเนินการบางอย่างทำซ้ำได้อย่างปลอดภัยแม้ไม่มีเฮดเดอร์:

PUT /v1/cards-by-external-id/{external_id} สร้างหรือแทนที่การ์ดที่มี ID ของคุณ การส่งซ้ำด้วยเนื้อหาเดิมจะไม่เปลี่ยนแปลงอะไร
เอกสารของ แหล่งข้อมูลแบบกำหนดเอง ระบุตัวด้วย external_id ของคุณ การส่งเอกสารเดิมอีกครั้งจะได้ unchanged
คำตอบแบบสตรีมของ POST /v1/chat ใช้ฟิลด์ request_id ในเนื้อหาคำขอแทนเฮดเดอร์ ดู สร้างบอตถาม-ตอบ

การลองใหม่อย่างปลอดภัย

ใช้คีย์ร่วมกับกฎการลองใหม่ใน ข้อผิดพลาด สร้างคีย์ครั้งเดียวก่อนความพยายามส่งครั้งแรก และส่งคีย์นั้นไปกับทุกความพยายามส่งของการดำเนินการเดียวกัน