Idempotency

~3 phút đọc

Mạng có thể đứt giữa lúc API đã xử lý xong và lúc bạn nhận được phản hồi. Với route ghi, header Idempotency-Key cho phép bạn gửi lại cùng một yêu cầu mà không tạo bản ghi thứ hai: API nhận ra khoá đã dùng và trả lại kết quả của lần đầu.

Quy tắc của khoá

Một chuỗi từ 1 đến 255 ký tự ASCII in được, không có khoảng trắng. UUID là lựa chọn phù hợp.
Khoá có hiệu lực 24 giờ kể từ lần dùng đầu.
Route ghi khai báo mức: required (bắt buộc), như tạo tài khoản ngân hàng, hoặc optional (tuỳ chọn), như cập nhật hay lưu trữ tài khoản. Route đọc (GET) không dùng khoá. Mức của từng route nằm ở x-dt-idempotent trong đặc tả OpenAPI.
Hai yêu cầu được coi là cùng một yêu cầu khi cùng phương thức, đường dẫn, tham số truy vấn (không phụ thuộc thứ tự), thân JSON (không phụ thuộc thứ tự khoá) và cùng người gọi. Cùng một khoá từ người gọi khác là yêu cầu khác.

Bốn trường hợp

Tình huống	Kết quả
Khoá mới.	API xử lý yêu cầu như bình thường.
Cùng khoá, cùng yêu cầu, lần đầu đã xong.	API trả lại đúng trạng thái, header chính và thân của lần đầu, kèm `Idempotency-Replayed: true`.
Cùng khoá nhưng yêu cầu khác.	`422 idempotency_key_reused`. Dùng khoá mới cho yêu cầu mới.
Cùng khoá, cùng yêu cầu, lần đầu vẫn đang chạy.	`409 idempotency_in_flight` kèm `Retry-After: 2`. Chờ rồi gửi lại. Một lượt chiếm khoá quá 120 giây được thu hồi để yêu cầu chạy lại.

Thiếu Idempotency-Key ở route required nhận 400 idempotency_key_required, kiểm tra trước cả khi xác thực thân yêu cầu.

Khi lần đầu thất bại

Khoá không bị "đốt" bởi lỗi tạm thời. Phản hồi 5xx và các mã báo yêu cầu chưa được xử lý (401, 403, 408, 425, 429) nhả khoá, nên lần gửi lại chạy ngay. Các lỗi 4xx còn lại được lưu và phát lại, vì cùng một yêu cầu sẽ lỗi theo cùng một cách. Phản hồi lớn hơn 256 KB không được lưu nguyên văn: bản phát lại giữ trạng thái và header, và chỉ tới tài nguyên đã tạo.

SDK làm giúp bạn

SDK TypeScript và Python tự gắn Idempotency-Key (UUIDv7) cho mỗi lời gọi tới route khai báo idempotent, sinh một lần cho lời gọi và giữ nguyên qua mọi lần thử lại. Khoá bạn tự truyền luôn được ưu tiên. Vì vậy SDK có thể thử lại cả lỗi 5xx và lỗi mạng của route ghi mà không sợ ghi trùng.

Các lỗi liên quan

HTTP	Mã lỗi	Thử lại	Ý nghĩa
400	`idempotency_key_required`	không	Thiếu header Idempotency-Key
422	`idempotency_key_reused`	không	Idempotency-Key đã dùng cho yêu cầu khác
409	`idempotency_in_flight`	có	Yêu cầu cùng Idempotency-Key đang xử lý