Cách hoạt động
- Thêm
Idempotency-Key: <giá trị duy nhất>vào thao tác ghi. Một UUID ngẫu nhiên cho mỗi thao tác nghiệp vụ là khóa tốt. Mọi thao tác ghi trong tham chiếu API đều nhận header này. - Cùng khóa với cùng nội dung trong 24 giờ trả lại câu trả lời đã lưu: cùng trạng thái, cùng nội dung. Không có gì chạy hai lần.
- Cùng khóa với nội dung khác là
422 IDEMPOTENCY_KEY_REUSED. Hãy dùng khóa mới cho yêu cầu mới. - Cùng khóa khi yêu cầu đầu còn đang chạy là
409 IDEMPOTENCY_IN_PROGRESSkèmRetry-After: 2. Chờ rồi gửi lại đúng yêu cầu đó. - Yêu cầu bị lỗi không được lưu: gửi lại với cùng khóa và nó chạy lại.
- Khóa được tách theo tenant, người gọi, ứng dụng, phương thức và đường dẫn. Hai ứng dụng, hay hai thao tác khác nhau, không bao giờ dùng chung khóa.
- Không có header thì máy chủ tự đặt một khóa, nên việc gửi lại không được loại trùng. Khóa đang dùng được trả về trong header phản hồi
Idempotency-Key.
curl -sS https://api.stracker.vn/v1/trips \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 7b6a2c0e-5c53-4b60-9b3e-2d1f6a0c9d11" \
-d '{"routeId": 4, "date": "2026-11-20"}'Khóa bí mật không bao giờ được phát lại
Các câu trả lời hiện khóa bí mật một lần (tạo subscription webhook, đổi khóa của nó) được lưu không kèm khóa. Phát lại trả cùng subscription nhưng không có secret. Nếu bạn mất phản hồi đầu tiên, hãy đổi khóa bí mật và giữ khóa mới.
Khi nào gửi lại
- Gửi lại với cùng khóa: lỗi mạng hoặc hết thời gian chờ,
5xx,429(sauRetry-After),409 IDEMPOTENCY_IN_PROGRESS. - Đừng gửi lại một
4xxnói về chính yêu cầu (400,403,404,409do xung đột): sửa yêu cầu và dùng khóa mới. - Thao tác đọc (
GET) lặp lại an toàn và không cần khóa.