Gửi lại an toàn
Với request POST, hãy gửi header Idempotency-Key. Khi mạng chập chờn hoặc client hết thời gian chờ, bạn gửi lại cùng key mà không lo bị trừ lượt hai lần.
Idempotency-Key: 6f1c2a4e-8d0b-4c1e-9a57-2f3b8e7d1c90
| Quy định | Giá trị |
|---|---|
| Định dạng | 1 đến 64 ký tự A-Z a-z 0-9 _ -, ví dụ UUID |
| Phạm vi | Riêng cho từng ứng dụng |
| Thời gian lưu | 24 giờ |
Kết quả khi gửi lại cùng key
Áp dụng khi gửi lại cùng key và cùng body:
| Lần trước nhận | Lần gửi lại |
|---|---|
200 (có kết luận, đã trừ lượt) | Trả lại đúng response cũ. Không gọi xác thực lần nữa, không trừ thêm lượt. |
400 INVALID_CARD_DATA hoặc 400 ID_NUMBER_MISMATCH | Trả lại đúng lỗi cũ. Dữ liệu không đổi thì kết quả không đổi. |
402, 429, 5xx (không trừ lượt) | Xử lý lại như một lần gọi mới. |
Response được trả lại từ lần trước có header:
Idempotent-Replayed: true
Ví dụ: đơn vị hết lượt và nhận 402. Sau khi được cấp thêm lượt, bạn gửi lại đúng key cũ và request được xử lý bình thường. Lỗi tạm thời của hệ thống xác thực cũng xử lý như vậy.
Xung đột key (409)
| Mã | Nguyên nhân | Cách xử lý |
|---|---|---|
IDEMPOTENCY_CONFLICT | Cùng key nhưng body khác | Dùng key mới cho request mới |
REQUEST_IN_PROGRESS | Cùng key, lần gọi trước chưa xong | Chờ rồi gửi lại cùng key |
Nên làm
- Tạo key một lần cho mỗi thao tác nghiệp vụ, ví dụ mỗi hồ sơ, và lưu lại cùng thao tác đó.
- Khi timeout hoặc lỗi mạng, gửi lại với cùng key.
- Không dùng một key cho hai nội dung khác nhau.