Hướng dẫn August 6, 2026

Xử lý lỗi LINE MINI App Service Message API: 400, 401, 403, 429 và 500

Cách nhanh nhất để xử lý lỗi LINE MINI App Service Message API là xác định lỗi nằm ở bước cấp service notification token hay gửi tin. 400, 401, 403 thường cần sửa request, credential hoặc permission; 429 yêu cầu giảm tốc độ; với 500, hãy giữ bằng chứng trước khi retry. Sau mỗi lần gửi thành công, phải lưu atomically notification token mới trước khi worker tiếp theo chạy.

Điểm chính

POST /message/v3/notifier/token và POST /message/v3/notifier/send?target=service có thể trả cùng status nhưng khác nguyên nhân, nên log phải có endpoint và giai đoạn.
LIFF access token có thể bị thu hồi khi người dùng đóng LIFF app dù chưa hết hạn.
Một lần gửi thành công thường làm mới service notification token; lưu token cùng remainingCount và expiresIn.
429 là tín hiệu giảm traffic, không phải rút ngắn retry. LINE yêu cầu không tạo lượng request lớn để load test platform.
Không gửi lại mù quáng khi chưa biết kết quả. Tài liệu chính thức không mô tả idempotency key cho endpoint này.

Bảng lỗi LINE MINI App Service Message API

API reference chính thức có hai server-side call. Token endpoint đổi LIFF access token lấy service notification token gắn với một người dùng. Send endpoint kết hợp token đó với template đã được duyệt.

Status	Cấp token	Gửi tin	Kiểm tra đầu tiên
`400 Bad Request`	Body sai hoặc dùng lại cùng LIFF access token trong thời gian ngắn	Body/params sai hoặc người nhận không tồn tại	Xác minh request của đúng endpoint
`401 Unauthorized`	Channel access token hoặc LIFF access token sai	Channel access token hoặc service notification token sai	Xác định đúng loại token của operation
`403 Forbidden`	Channel không được phép cấp token	Channel không được phép gửi hoặc không thấy `templateName`	Kiểm tra environment, verification và template
`429 Too Many Requests`	Vượt rate	Vượt rate	Dừng traffic thử nghiệm, backoff và giảm concurrency
`500 Internal Server Error`	Bảng cấp token chính thức liệt kê server error	Nếu send trả `5xx`, xử lý như incident; bảng riêng của send không liệt kê `500`	Giữ evidence và kiểm tra notice chính thức

Bảng này chỉ để phân loại; vẫn phải đọc response body. Hãy lưu status, endpoint, thời gian, response đã redacted, channel/environment, template name và job ID nội bộ. Token thật phải ở secret store; application log chỉ lưu fingerprint một chiều để không lộ credential.

Runbook: xác định state trước khi retry

1. Tách cấp token khỏi gửi tin

Ở bước cấp, xác nhận browser lấy token từ LIFF session hiện tại và chỉ gửi cho backend một lần. Không gọi Service Message API trực tiếp từ browser vì call còn cần channel access token. Mỗi LIFF access token chỉ được dùng để cấp một service notification token.

Ở bước gửi, kiểm tra riêng channel access token, service notification token mới nhất và templateName có suffix BCP 47 được hỗ trợ như _ja, _en, _zh-TW, _th. Token hợp lệ không bù được template thiếu trong channel.

Hướng dẫn notification token mô tả flow hai call bình thường. Chỉ áp dụng runbook này khi đã biết call nào hỏng.

2. Xử lý `400` theo từng endpoint

Khi cấp token, tìm double-click hoặc frontend retry đã gửi lại LIFF access token cũ. Khi gửi, so sánh params với template đã duyệt và kiểm tra giới hạn ký tự trước dispatch. LINE nêu rõ giá trị vượt hard limit sẽ không gửi được.

Không rotate mọi credential chỉ vì 400. Sửa request hoặc user state rồi tạo operation mới với job ID mới. Dùng checklist review template để kiểm tra biến và link trước production.

3. Truy vết owner và lifetime khi gặp `401`

Channel access token xác thực MINI App channel; LINE khuyến nghị stateless hoặc short-lived token.
LIFF access token chứng minh user session và có thể bị thu hồi khi LIFF app đóng.
Service notification token chỉ thuộc một user, không dùng cho user khác.

Nếu user đóng app trước khi backend exchange, mở lại LIFF flow và lấy token mới. Nếu send hỏng, kiểm tra worker đã đọc token mới từ response thành công gần nhất, không phải giá trị cũ trong queue snapshot.

4. Coi `403` là mismatch về permission hoặc deployment

403 khi cấp token nghĩa là channel không có quyền. Khi gửi, nó còn có thể nghĩa là template không tồn tại. Kiểm tra Developing/Published channel, production eligibility và template của locale đã được reflected.

Verified status không sửa sai template name; template đúng cũng không cấp production access cho Published channel chưa verified. Hướng dẫn verified và unverified tách hai điều kiện này.

5. Tuần tự hóa việc lưu notification token mới

Sau send thành công, LINE làm mới token nếu còn lifetime và message count. Hãy coi response là state transition:

đọc token hiện tại -> gửi một lần -> lưu token và counters mới -> chạy job tiếp theo

Dùng database transaction, compare-and-set version hoặc per-user queue để hai worker không dùng cùng token cũ. Nếu expiresIn và remainingCount đều bằng 0, tin đã được gửi nhưng token không được làm mới. Ghi nhận success và dừng service message tiếp theo với token đó.

6. Chỉ retry khi outcome có thể lặp an toàn

Không retry 400, 401, 403 cho tới khi request, credential hoặc authorization state thay đổi. Với 429, dùng backoff có jitter và giảm concurrency; không load test production API. Với 500 rõ ràng, lưu request record, kiểm tra LINE status/news rồi retry bằng controlled job.

Timeout sau dispatch rất nguy hiểm: client có thể không biết LINE đã nhận message và đổi token hay chưa. Vì không có idempotency key được công bố, blind retry có thể tạo thông báo trùng. Chuyển outcome chưa chắc chắn sang reconciliation hoặc operator review.

UnifyPort phù hợp ở đâu

UnifyPort không cấp LINE service notification token, không duyệt MINI App template, không đổi verification status và không khắc phục lỗi Service Message API chính thức. Hãy dùng đường chính thức của LINE cho transactional notification gắn với hành động trong MINI App.

UnifyPort giải quyết nhu cầu riêng: nhận tin nhắn khách hàng thông thường từ LINE account đã kết nối. Tin inbound được hỗ trợ đến dưới dạng message.received event chuẩn hóa. Nếu webhook endpoint có signing_secret, delivery gồm X-Device-Timestamp và X-Device-Signature; xác minh HMAC-SHA256 bằng raw body trước khi routing.

Giữ hai state machine độc lập. Service notification token thuộc transaction flow của MINI App; reply khách hàng thuộc support flow. Nối chúng bằng order hoặc reservation ID của hệ thống bạn, không dùng chung platform token.

Giới hạn và đánh đổi

Service Message API chính thức là lựa chọn đúng khi MINI App đã verified cần gửi confirmation, result hoặc reminder đã được duyệt. Unofficial interface không cung cấp platform-native template, identity và policy control đó.

Unofficial interface không bỏ eligibility của LINE, không khôi phục token hết hạn, không tăng giới hạn năm tin và không biến support reply thành service message. Vai trò của nó là chuyển conversation thông thường được hỗ trợ qua một inbound API thống nhất.

FAQ

Vì sao LIFF access token chưa hết hạn lại trả `401`?

LINE có thể thu hồi token khi user đóng LIFF app. Hãy lấy token từ LIFF session mới và exchange đúng một lần.

Vì sao cấp token thành công nhưng send trả `403`?

Hai endpoint có kiểm tra khác nhau. Send có thể thiếu permission ở environment đó hoặc không tìm thấy templateName.

Có thể retry service message sau timeout không?

Không mù quáng. Message và token có thể đã đổi state. Hãy reconciliation trước khi gửi lại.

Incident log cần lưu gì?

Thời gian, method, endpoint, status, redacted response, channel/environment, template, job ID và token fingerprint an toàn. Token thật chỉ ở protected store.

`remainingCount: 0` và `expiresIn: 0` sau `200` nghĩa là gì?

Message đã gửi nhưng LINE không làm mới notification token. Ghi nhận success và không dùng token đó nữa.

Bước tiếp theo

Xây status dispatcher theo LINE MINI App API reference và thử một controlled failure cho mỗi endpoint trước release. Nếu nhu cầu riêng là nhận tin LINE thông thường, hãy đọc hướng dẫn ủy quyền LINE của UnifyPort sau khi notification flow ổn định.

Nguồn

Các nguồn chính thức của LINE được kiểm tra ngày 06-08-2026: