แก้ข้อผิดพลาด LINE MINI App Service Message API: 400, 401, 403, 429 และ 500
วิธีวิเคราะห์ข้อผิดพลาด LINE MINI App Service Message API ที่เร็วที่สุดคือแยกก่อนว่าล้มเหลวตอนออก service notification token หรือตอนส่งข้อความ 400, 401, 403 มักต้องแก้ request, credential หรือ permission ส่วน 429 ต้องลดความเร็ว และ 500 ควรเก็บหลักฐานก่อน retry ทุกครั้งที่ส่งสำเร็จ ต้องบันทึก notification token ตัวใหม่แบบ atomic ก่อนให้ worker ถัดไปทำงาน
สรุปสำคัญ
POST /message/v3/notifier/tokenและPOST /message/v3/notifier/send?target=serviceอาจคืน status เดียวกันด้วยสาเหตุต่างกัน จึงต้อง log ทั้ง endpoint และขั้นตอน- LIFF access token อาจถูกเพิกถอนเมื่อผู้ใช้ปิด LIFF app แม้ยังไม่หมดอายุ
- การส่งสำเร็จมักต่ออายุ service notification token ให้บันทึก token ใหม่พร้อม
remainingCountและexpiresIn 429หมายถึงต้องลด traffic ไม่ใช่ retry ให้ถี่ขึ้น LINE ระบุว่าไม่ควรส่ง request จำนวนมากเพื่อ load test platform- อย่าส่งซ้ำโดยไม่รู้ผลลัพธ์ เพราะเอกสารทางการไม่ได้ระบุ idempotency key สำหรับ endpoint นี้
ตารางข้อผิดพลาด LINE MINI App Service Message API
LINE MINI App API reference ทางการมี server-side call สองรายการ token endpoint ใช้ LIFF access token เพื่อรับ service notification token ที่ผูกกับผู้ใช้หนึ่งคน ส่วน send endpoint ใช้ token นั้นกับ template ที่ผ่านการตรวจแล้ว
| Status | ออก token | ส่งข้อความ | สิ่งแรกที่ตรวจ |
|---|---|---|---|
400 Bad Request | body ไม่ถูกต้อง หรือใช้ LIFF access token เดิมซ้ำในช่วงเวลาสั้น | body/params ไม่ถูกต้อง หรือไม่มีผู้รับ | ตรวจ request ของ endpoint ที่ล้มเหลว |
401 Unauthorized | channel access token หรือ LIFF access token ไม่ถูกต้อง | channel access token หรือ service notification token ไม่ถูกต้อง | ระบุชนิด token ของ operation |
403 Forbidden | channel ไม่มีสิทธิ์ออก token | channel ไม่มีสิทธิ์ส่ง หรือไม่พบ templateName | ตรวจ environment, verification และ template |
429 Too Many Requests | เกิน rate | เกิน rate | หยุด traffic ทดสอบ ใช้ backoff และลด concurrency |
500 Internal Server Error | ตารางออก token ทางการระบุ server error | ถ้า send คืน 5xx ให้จัดเป็น incident เพราะตารางเฉพาะ send ไม่ได้ระบุ 500 | เก็บหลักฐานและดูประกาศทางการ |
ตารางนี้ใช้แยกทางตรวจสอบ ไม่ได้แทน response body ควรเก็บ status, endpoint, เวลาส่ง, response ที่ redacted แล้ว, channel/environment, template name และ job ID ภายใน เก็บ access token กับ notification token จริงไว้ใน secret store เท่านั้น ส่วน application log ให้ใช้ fingerprint ทางเดียวเพื่อไม่เปิดเผย credential
Runbook: ระบุ state ก่อนตัดสินใจ retry
1. แยกการออก token ออกจากการส่งข้อความ
ตอนออก token ให้ยืนยันว่า browser ได้ token จาก LIFF session ปัจจุบันและส่งให้ backend เพียงครั้งเดียว อย่าเรียก Service Message API จาก browser โดยตรง เพราะ request ยังต้องใช้ channel access token LINE อนุญาตให้ LIFF access token หนึ่งตัวออก service notification token ได้หนึ่งตัวเท่านั้น
ตอนส่ง ให้ตรวจ channel access token, service notification token ล่าสุด และ templateName ที่มี suffix BCP 47 ที่รองรับ เช่น _ja, _en, _zh-TW, _th แยกกัน token ที่ถูกต้องไม่ช่วยหากไม่มี template ใน channel
บทสอน notification token อธิบาย flow ปกติสอง call ให้ใช้ runbook นี้เมื่อระบุได้แล้วว่า call ใดล้มเหลว
2. แก้ 400 ตาม endpoint
ตอนออก token ให้หา double-click หรือ frontend retry ที่ส่ง LIFF access token ซึ่งใช้ไปแล้วซ้ำ ตอนส่ง ให้เทียบ params กับ template ที่อนุมัติและตรวจจำนวนอักขระก่อน dispatch LINE ระบุว่าค่าที่เกิน hard limit จะส่งไม่ได้
อย่า rotate credential ทั้งหมดเพราะ 400 ให้แก้ request หรือ user state แล้วสร้าง operation ใหม่ด้วย job ID ใหม่ ใช้ checklist ตรวจ template เพื่อตรวจตัวแปรและ link ก่อน production
3. ตรวจ owner และ lifetime ของ token เมื่อเจอ 401
- Channel access token ใช้ยืนยัน MINI App channel โดย LINE แนะนำ stateless หรือ short-lived token
- LIFF access token ยืนยัน user session ปัจจุบัน และอาจถูกเพิกถอนเมื่อปิด LIFF app
- Service notification token เป็นของ user คนเดียวและใช้กับคนอื่นไม่ได้
หาก user ปิด app ก่อน backend exchange ให้เปิด LIFF flow ใหม่และรับ token ใหม่ หาก send ล้มเหลว ให้ตรวจว่า worker อ่าน token จาก response ที่สำเร็จล่าสุด ไม่ใช่ค่าเก่าใน queue snapshot
4. มอง 403 เป็น permission หรือ deployment mismatch
403 ตอนออก token หมายถึง channel ไม่มีสิทธิ์ ส่วนตอนส่งอาจหมายถึงไม่พบ template ด้วย ตรวจว่าเรียก Developing หรือ Published channel ที่ถูกต้อง มี production eligibility และ template ของ locale นั้นอยู่ในสถานะ reflected
Verified status ไม่แก้ชื่อ template ที่ผิด และ template ที่ถูกต้องก็ไม่ให้ production permission แก่ Published channel ที่ยังไม่ verified คู่มือ verified กับ unverified แยกเงื่อนไขสองเรื่องนี้ไว้
5. บันทึก notification token ใหม่แบบเรียงลำดับ
หลังส่งสำเร็จ LINE จะต่ออายุ token หากยังมี lifetime และ message count ให้มอง response เป็น state transition:
อ่าน token ปัจจุบัน -> ส่งหนึ่งครั้ง -> บันทึก token และ counters ใหม่ -> ปล่อย job ถัดไปใช้ database transaction, compare-and-set version หรือ per-user queue เพื่อไม่ให้สอง worker ใช้ token เก่าตัวเดียวกัน หาก expiresIn และ remainingCount เป็น 0 ทั้งคู่ ข้อความถูกส่งแล้วแต่ token ต่ออายุไม่ได้ ให้บันทึก success และหยุด service message ถัดไปด้วย token นั้น
6. Retry เฉพาะเมื่อ outcome ทำซ้ำได้อย่างปลอดภัย
อย่า retry 400, 401, 403 จนกว่า request, credential หรือ authorization state จะเปลี่ยน สำหรับ 429 ใช้ backoff ที่มี jitter และลด concurrency อย่า load test production API สำหรับ 500 ที่ชัดเจน ให้เก็บ request record ตรวจ LINE status/news แล้ว retry ผ่าน controlled job
กรณี timeout หลัง dispatch อันตรายกว่า เพราะ client อาจไม่รู้ว่า LINE รับ message และเปลี่ยน token แล้วหรือยัง เมื่อไม่มี idempotency key ที่ประกาศ blind retry อาจสร้างข้อความซ้ำ ควรส่ง outcome ที่ไม่แน่ชัดไป reconciliation หรือ operator review
UnifyPort เหมาะกับส่วนใด
UnifyPort ไม่ออก LINE service notification token ไม่อนุมัติ MINI App template ไม่เปลี่ยน verification status และไม่แก้ error ของ Service Message API ทางการ ใช้เส้นทางทางการของ LINE สำหรับ transactional notification ที่ผูกกับการกระทำใน MINI App
UnifyPort ดูแลอีกความต้องการหนึ่ง คือรับข้อความลูกค้าทั่วไปจาก LINE account ที่เชื่อมต่อแล้ว ข้อความ inbound ที่รองรับจะมาถึงเป็น message.received event มาตรฐาน หาก webhook endpoint มี signing_secret delivery จะมี X-Device-Timestamp และ X-Device-Signature ให้ตรวจ HMAC-SHA256 ด้วย raw body ก่อน routing
แยก state machine สองชุดนี้ไว้ Service notification token อยู่ใน transaction flow ของ MINI App ส่วน reply ลูกค้าอยู่ใน support flow ให้เชื่อมด้วย order หรือ reservation ID ของระบบคุณ ไม่ใช่ใช้ platform token ร่วมกัน
ข้อจำกัดและสิ่งที่ต้องแลก
Service Message API ทางการเหมาะเมื่อ MINI App ที่ verified ต้องส่ง confirmation, result หรือ reminder ที่อนุมัติแล้ว Unofficial interface ไม่สามารถให้ platform-native template, identity และ policy control เหล่านี้ได้
Unofficial interface ไม่ยกเลิก eligibility ของ LINE ไม่กู้ token หมดอายุ ไม่เพิ่มขีดจำกัดห้าข้อความ และไม่เปลี่ยน support reply เป็น service message หน้าที่ของมันคือส่ง conversation ทั่วไปที่รองรับผ่าน inbound API เดียว
FAQ
ทำไม LIFF access token ที่ยังไม่หมดอายุคืน 401
LINE อาจเพิกถอน token เมื่อ user ปิด LIFF app ให้รับ token จาก LIFF session ใหม่และ exchange เพียงครั้งเดียว
ทำไมออก token สำเร็จแต่ send คืน 403
สอง endpoint ตรวจคนละอย่าง Send อาจไม่มี permission ใน environment นั้น หรือไม่พบ templateName
Retry service message หลัง timeout ได้ไหม
อย่า retry โดยไม่ตรวจ Message และ token อาจเปลี่ยน state แล้ว ให้ reconciliation ก่อนส่งอีกครั้ง
Incident log ควรเก็บอะไร
เก็บเวลา, method, endpoint, status, redacted response, channel/environment, template, job ID และ token fingerprint ที่ปลอดภัย ส่วน token จริงเก็บใน protected store
remainingCount: 0 และ expiresIn: 0 หลัง 200 หมายถึงอะไร
Message ถูกส่งแล้ว แต่ LINE ต่ออายุ notification token ไม่ได้ ให้บันทึก success และอย่าใช้ token นั้นอีก
ขั้นตอนถัดไป
สร้าง status dispatcher ตาม LINE MINI App API reference และทดสอบ controlled failure อย่างละหนึ่งครั้งสำหรับแต่ละ endpoint ก่อน release หากอีกความต้องการคือรับข้อความ LINE ทั่วไป ให้อ่าน คู่มือยืนยันบัญชี LINE ของ UnifyPort หลัง notification flow ทางการเสถียรแล้ว
แหล่งข้อมูล
ตรวจแหล่งข้อมูล LINE ทางการเมื่อ 6 สิงหาคม 2026: