LINE X-Line-Retry-Key: thử lại sau timeout mà không gửi trùng
Với các phương thức gửi LINE Messaging API có hỗ trợ, hãy thêm X-Line-Retry-Key ngay từ yêu cầu đầu tiên. Sau timeout hoặc lỗi máy chủ cho phép thử lại, dùng lại cùng khóa, người nhận và nội dung. Tạo UUID dạng thập lục phân cho mỗi yêu cầu logic mới. Nếu 409 cho biết khóa đã được chấp nhận, hãy dừng, không đổi khóa để gửi tiếp. Cơ chế này ngăn chấp nhận trùng trong thời hạn quy định, nhưng không bảo đảm người dùng nhận được tin nhắn.
Điểm chính
- Push, multicast, narrowcast và broadcast hỗ trợ retry key; không phải mọi LINE API đều hỗ trợ.
- Lưu bền vững khóa và yêu cầu gốc trước khi gửi, không đợi đến lúc có lỗi.
- LINE quy định khóa có hiệu lực 24 giờ tính từ yêu cầu đầu tiên.
- Tách biệt việc chấp nhận yêu cầu, giao tin cho người nhận và xác nhận webhook đầu vào.
X-Line-Retry-Key bảo vệ điều gì?
Timeout chỉ cho biết ứng dụng không nhận được phản hồi. LINE có thể đã chấp nhận yêu cầu gửi. Tạo UUID mới cho mỗi lần thử sẽ biến một kết quả chưa rõ thành một yêu cầu độc lập khác.
Theo hướng dẫn thử lại của LINE, khi yêu cầu có khóa đã được chấp nhận, các lần thử tiếp theo dùng cùng khóa sẽ bị từ chối là trùng lặp. Khóa phải có ngay từ lần đầu. Thêm khóa sau khi một yêu cầu không có khóa bị timeout không thể bảo vệ ngược lại lần gửi trước đó.
| Phương thức gửi | Hỗ trợ retry key theo tài liệu LINE |
|---|---|
| Push | Có |
| Multicast | Có |
| Narrowcast | Có |
| Broadcast | Có |
| API khác, gồm reply messages | Không nằm trong danh sách này; đừng thêm header cho mọi lệnh gọi |
LINE nêu rõ rằng thêm header này vào API không hỗ trợ sẽ trả về 400. Đây cũng không phải luồng notification token của LINE MINI App. Nếu đang xử lý luồng đó, hãy dùng hướng dẫn xử lý lỗi Service Message API, không áp dụng quy tắc của bài này.
Lưu bản ghi trước khi gọi mạng
Phần dưới là đề xuất thiết kế ứng dụng, không phải các trường bổ sung của LINE API.
Tạo bản ghi gửi đi bền vững gồm mã thao tác nghiệp vụ, danh tính channel, phương thức gửi, toàn bộ request body, UUID thử lại, thời điểm thử đầu tiên, hạn chót và trạng thái xử lý. Bảo vệ dữ liệu người nhận và nội dung theo chính sách lưu giữ. Đọc access token từ cấu hình an toàn; không đưa token vào bản ghi tác vụ hoặc nhật ký thông thường.
Lưu xong mới gửi. Mỗi lần thử lại phải đọc khóa và yêu cầu đã lưu, không dựng lại tin nhắn từ dữ liệu đơn hàng hay khách hàng có thể đã thay đổi. LINE yêu cầu giữ nguyên nội dung và người nhận khi dùng lại khóa.
Đặt mã thao tác nghiệp vụ duy nhất và dùng cơ chế nhận việc độc quyền hoặc khóa cho worker. Nếu không, hai worker có thể tạo hai UUID cho cùng một hành động, và cả hai yêu cầu đều được chấp nhận. Retry key nhận diện yêu cầu có cùng khóa, chứ không suy ra hai tác vụ riêng biệt có cùng ý nghĩa nghiệp vụ.
Nếu nhiều công cụ dùng chung một Official Account, hãy chỉ định hệ thống chịu trách nhiệm cho từng loại gửi. Danh sách kiểm tra khi dùng nhiều công cụ giải thích ranh giới channel dùng chung; outbox trong ứng dụng quản lý quyền xử lý từng lần gửi.
Quyết định theo kết quả thực tế
Làm theo hướng dẫn thử lại theo mã trạng thái của LINE. Không coi mọi phản hồi không thành công là quyền gửi thêm một lần.
| Kết quả quan sát | Hành động worker nên thực hiện |
|---|---|
2xx | Ghi nhận đã được chấp nhận và dừng thử lại |
| Timeout hoặc lỗi máy chủ cho phép thử lại | Lên lịch trong ngân sách cho phép, giữ nguyên khóa và yêu cầu |
409 cho biết khóa đã được chấp nhận | Lưu x-line-accepted-request-id, ghi nhận lần chấp nhận trước và dừng |
4xx khác | Dừng lặp lại yêu cầu không đổi, kiểm tra yêu cầu hoặc giới hạn |
| Hết thời hạn nhưng chưa rõ đã được chấp nhận hay chưa | Chuyển sang đối soát hoặc người vận hành, không tự đổi khóa |
Trong phản hồi báo trùng, x-line-accepted-request-id xác định yêu cầu đã thành công. Phân biệt nó với x-line-request-id, mã của từng lần gọi. Lưu trạng thái, thời điểm và thông tin chẩn đoán đã che dữ liệu nhạy cảm; không phân nhánh chỉ dựa vào chuỗi thông báo lỗi.
LINE khuyến nghị exponential backoff và lưu ý rằng các lần thử lại vẫn tính vào giới hạn tốc độ API. Bộ lập lịch cần có giới hạn số lần riêng và không xếp lịch vượt quá hiệu lực 24 giờ của khóa. Thời hạn tính từ yêu cầu đầu tiên, không bắt đầu lại sau mỗi lần thử. Ứng dụng có thể đặt hạn chót sớm hơn để thận trọng.
Khóa hết hạn không làm kết quả chưa rõ trở nên rõ ràng. Khóa mới là một quyết định gửi mới và có thể lặp lại tin đã được chấp nhận. Cần đối soát hoặc phê duyệt rõ ràng, không xem đổi khóa là bước khôi phục thông thường.
Được chấp nhận không có nghĩa là đã giao
LINE cảnh báo rằng retry key không bảo đảm giao tin đáng tin cậy cho người nhận. Ví dụ, người dùng có thể đã chặn Official Account, nên không thể suy ra việc giao tin từ phản hồi chấp nhận. Sau khi được chấp nhận, gửi lại cùng khóa không phải cơ chế sửa lỗi giao tin.
Trong ứng dụng, tách “LINE đã chấp nhận” khỏi “khách hàng đã đọc”. Tương tự, webhook receiver của bạn trả thành công chỉ xác nhận tiếp nhận sự kiện đầu vào, không chứng minh tin trả lời đã được gửi.
Giữ riêng hợp đồng tích hợp của UnifyPort
Giao diện không chính thức của UnifyPort kết nối tài khoản nhắn tin và cung cấp sự kiện chuẩn hóa như message.received. Đây không phải một công cụ gửi khác trong cùng channel LINE Official Account Messaging API. Tài liệu gửi công khai của UnifyPort cũng không nêu hỗ trợ X-Line-Retry-Key.
Trước khi triển khai thử lại gửi tin, hãy đọc đặc tả gửi tin văn bản. Không sao chép thời hạn 24 giờ hoặc phản hồi chấp nhận trùng của LINE vào tích hợp này. Mã truy vết yêu cầu cũng không tự động bảo đảm tính idempotent.
Với đầu vào, bật signing_secret và xác minh X-Device-Signature bằng HMAC-SHA256 của X-Device-Timestamp, dấu chấm và request body nguyên gốc. Quy tắc xác nhận và thử lại nằm trong tài liệu phân phối webhook. Loại bỏ sự kiện đầu vào trùng và ngăn gửi đầu ra trùng là hai việc khác nhau. Điều này cũng quan trọng khi một hàng đợi tiếp nhận nhiều kênh như LINE, Zalo và WhatsApp: hợp đồng gửi của kênh này không tự áp dụng cho kênh khác.
Nếu cần chức năng gửi của Official Account, hãy dùng Messaging API chính thức. Chuyển sang giao diện tài khoản thông thường không giải quyết kết quả chưa rõ của yêu cầu đã gửi qua API chính thức.
Câu hỏi thường gặp
Có thể tạo khóa sau timeout đầu tiên không?
Không thể dùng nó để bảo vệ yêu cầu gốc. API có hỗ trợ phải nhận khóa từ lần thử đầu tiên.
Nhận 409 thì đổi UUID để gửi lại?
Không, nếu nó cho biết cùng khóa đó đã được chấp nhận. Lưu mã yêu cầu đã được chấp nhận và kết thúc thử lại thao tác đó.
Giữ khóa nhưng đổi người nhận được không?
Không. LINE yêu cầu nội dung và người nhận trùng với yêu cầu ban đầu. Thay đổi hành động nghiệp vụ cần quyết định riêng, không phải sửa yêu cầu đang thử lại.
Cơ chế này dùng được cho mọi API tin nhắn LINE?
Không. Chỉ áp dụng cho các phương thức được liệt kê là hỗ trợ. Không chuyển quy tắc này sang MINI App service messages hay lệnh gửi UnifyPort.
Bước tiếp theo và nguồn
Kiểm tra một worker gửi đi: sau khi tiến trình gặp sự cố, nó có khôi phục được cùng khóa và cùng yêu cầu không? Thử ranh giới này bằng mock cục bộ trước, rồi mới kiểm tra một lần gửi thực tế có kiểm soát. Với luồng tài khoản kết nối, hãy xem tài liệu gửi của UnifyPort.
Nguồn chính thức được kiểm tra ngày 2026-09-28:
Biến tích hợp nhắn tin thành một pipeline sản phẩm ổn định.
Bắt đầu bằng cách gửi qua một API, rồi đưa mọi tin nhắn inbound trở lại hệ thống kinh doanh bằng sự kiện chuẩn.