Cuộc gọi mạng đôi khi thất bại theo những cách khiến bạn không chắc request đã được xử lý hay chưa. Idempotency key giúp việc thử lại trở nên an toàn: gửi lại cùng request với cùng key, MADIAD Hub sẽ trả về kết quả ban đầu thay vì đăng thêm một lần nữa.
Gửi idempotency key
Thêm header Idempotency-Key với giá trị do bạn tự chọn. Lý tưởng nhất là dùng một UUID riêng cho mỗi hành động logic. Hub cũng chấp nhận X-Idempotency-Key hoặc X-Request-Id như các header tương đương.
Cách hoạt động
- Request đầu tiên với một key: được xử lý bình thường, kết quả được lưu lại theo key đó.
- Gửi lại cùng key và cùng nội dung: trả về kết quả đã lưu, không tạo thêm bài đăng nào, và response kèm header
Idempotent-Replayed: true.
- Cùng key nhưng khác nội dung: bị từ chối với
409 idempotency_conflict. Không có gì được đăng.
- Key khác nhau: được xử lý như một request hoàn toàn mới.
Tạo key trước lần gửi đầu tiên và dùng lại cho mọi lần thử lại của cùng hành động đó. Tạo key mới khi thử lại sẽ làm mất tác dụng của cơ chế này.
Phân biệt kết quả phát lại với một lần đăng thật
Response phát lại giống hệt response gốc: cùng request_id, cùng trạng thái. Đó chính là mục đích của cơ chế, nhưng nó cũng có nghĩa là một automation bị kẹt key sẽ liên tục nhận về những response trông như thành công trong khi không có gì mới được đăng.
Vì vậy mọi response phát lại đều kèm một header:
Một lần đăng thật không bao giờ có header này. Nếu bạn chạy đăng bài tự động hoặc theo lịch, hãy coi header này là tín hiệu cảnh báo: nó nghĩa là key bạn vừa gửi đã được dùng rồi, nên nội dung bạn vừa gửi lên chưa được đăng.
Mỗi bài mới phải có một key mới. Bộ đếm ngừng tăng, một item workflow bị chạy lại, hay một template ghi cứng key đều dẫn tới việc gửi nội dung mới dưới một key đã dùng. Từ 26/07/2026, trường hợp nội dung khác nhau sẽ trả về 409 idempotency_conflict; trước đó hệ thống lặng lẽ trả lại kết quả cũ.
Khi kết quả chưa xác định
Việc đăng bài có thể lâu hơn khoảng thời gian MADIAD Hub được phép chờ. Khi đó request không bị báo là thất bại, vì bài rất có thể đã lên: bên mình ngừng chờ, còn nền tảng thì không ngừng làm việc.
Bạn nhận 502 với mã upstream_timeout, không có gì được hoàn lại, và key bạn gửi được chốt vào câu trả lời đó. Gửi lại cùng key sẽ nhận đúng 502 và đúng nội dung cũ. Đây là chủ ý: một automation phân nhánh theo mã trạng thái sẽ không thể ghi nhận nhầm một bài chưa rõ thành công.
Việc cần làm:
- Kiểm tra lịch sử đăng hoặc kiểm tra thẳng trên nền tảng trước khi làm bất cứ điều gì khác.
- Nếu bài chưa lên, hãy gửi lại với một
Idempotency-Key mới. Key cũ từ giờ luôn trả về kết quả “chưa xác định”.
- Đừng để automation tự retry cùng key rồi mong kết quả khác đi.
Khi nào nên dùng
Luôn dùng với bất kỳ request nào có tạo dữ liệu mới, đặc biệt là bài đăng. Cơ chế này thiết yếu khi:
- Một client hoặc công cụ workflow (n8n, queues, cron) tự động thử lại khi timeout.
- Một webhook hoặc job có thể được giao nhiều hơn một lần.
- Người dùng nhấp đúp vào nút đăng bài.
Key được giới hạn trong phạm vi tài khoản của bạn và được ghi nhớ đủ lâu để bao phủ các khung thời gian thử lại thực tế. 
