Idempotency

Idempotency

Route ที่เขียนข้อมูลเพื่อสร้างทรัพยากร (เช่น การสร้าง webhook endpoint การส่งเหตุการณ์ทดสอบ webhook หรือการอัปโหลดเข้าคลังความรู้) ต้องมี header Idempotency-Key เพื่อให้คุณลองคำขอซ้ำได้อย่างปลอดภัย — หลัง timeout, การเชื่อมต่อหลุด หรือกรณีใดๆ — โดยไม่เสี่ยงต่อการเกิดผลข้างเคียงซ้ำซ้อน

POST /api/v1/webhooks
Idempotency-Key: 7d6f0a2e-8b1c-4a3d-9e5f-2c1b0a3d4e5f
Content-Type: application/json

{ "url": "https://example.com/hooks/clienta", "events": ["conversation.created"] }

ใช้คีย์ที่สดใหม่และไม่ซ้ำกัน (UUID ก็ใช้ได้) ต่อการดำเนินการ เชิงตรรกะ หนึ่งครั้ง และใช้คีย์ เดิม ซ้ำเมื่อจะลองการดำเนินการ เดิม นั้นใหม่

การทำงาน

คำขอจะถูก claim ก่อน การทำงานใดๆ จะเกิดขึ้น — นี่คือสิ่งที่ทำให้ปลอดภัยจากการล่ม ไม่ใช่แค่ปลอดภัยจากการลองซ้ำ:

1. คำขอของคุณมาถึงพร้อม Idempotency-Key เซิร์ฟเวอร์จะพยายาม claim ชุด (organization, key, route, idempotencyKey) แบบ atomic
2. หากยังไม่มีใคร claim ชุดนี้มาก่อน คุณจะชนะการ claim และคำขอจะดำเนินการตามปกติ
3. หากถูก claim ไปแล้ว เซิร์ฟเวอร์จะดูว่าการพยายามครั้งก่อนหน้าเป็นอย่างไร แล้วตอบกลับตามตารางด้านล่าง

สถานการณ์	การตอบกลับ
คีย์เดิม คำขอ เหมือนเดิม เสร็จสมบูรณ์ไปแล้ว	การตอบกลับเดิม ถูกเล่นซ้ำ ทุกประการ (status code และ body เดิม)
คีย์เดิม แต่คำขอ ต่างกัน (body/method/path)	409 IDEMPOTENCY_KEY_REUSED
คีย์เดิม การพยายามครั้งก่อนหน้ายัง ดำเนินการอยู่	425 IDEMPOTENCY_IN_PROGRESS พร้อม header Retry-After
คีย์เดิม การพยายามครั้งก่อนหน้า ล่มกลางคัน (lease การประมวลผลหมดอายุ)	claim ถูกยึดคืนอย่างปลอดภัยและคำขอถูกลองใหม่ฝั่งเซิร์ฟเวอร์
ไม่มี header Idempotency-Key ใน route ที่ต้องการ	400 IDEMPOTENCY_KEY_REQUIRED

คีย์เดิม คำขอต่างกัน = 409 ไม่ใช่การเขียนทับแบบเงียบๆ

การใช้ Idempotency-Key ซ้ำสำหรับคำขอที่ต่างกันจริงๆ (body ต่างกัน, route ต่างกัน) ถือเป็นข้อผิดพลาดของผู้เรียก ไม่ใช่สิ่งที่ต้องเดา — คุณจะได้ 409 กลับมาทันที แทนที่จะให้คำขอใดคำขอหนึ่งชนะแบบเงียบๆ

อายุของบันทึก

• การ claim ระหว่างประมวลผลจะถูกถือไว้ภายใต้ lease ระยะสั้น (นานพอสำหรับคำขอหนึ่งครั้ง รวมถึงงานฐานข้อมูลใดๆ) — หากกระบวนการที่จัดการอยู่ล่ม การพยายามอื่นด้วยคีย์เดิมจะเข้ามารับช่วงต่ออย่างปลอดภัยเมื่อ lease หมดอายุ แทนที่จะได้ 425 ตลอดไป
• บันทึกที่เสร็จสมบูรณ์แล้ว — และการตอบกลับที่แคชไว้ — จะถูกเก็บไว้ 24 ชั่วโมง ตรงกับระยะเวลาที่เรายอมรับการลองซ้ำด้วยคีย์เดิม หลังจากช่วงเวลานี้ การใช้คีย์เดิมซ้ำจะเริ่มการดำเนินการใหม่ทั้งหมด

ขอบเขต

Idempotency key มีขอบเขตอยู่ที่ ตัวตนของคุณ + route ที่เจาะจง — ค่า Idempotency-Key เดียวกันที่ใช้กับสอง route ที่ต่างกัน หรือโดยสอง API key ที่ต่างกัน จะไม่มีวันชนกัน