Invalid token 18005 thường xuất hiện khi ứng dụng gọi Zalo API bằng access token không còn hợp lệ, không thuộc đúng ứng dụng hoặc bị truyền sai định dạng. Lỗi này có thể làm gián đoạn đăng nhập Zalo, kết nối Official Account, đồng bộ dữ liệu và các tác vụ backend cần xác thực.
Để xử lý triệt để, lập trình viên cần xác định token thuộc luồng nào, kiểm tra thời hạn, đối chiếu app ID, làm mới token đúng quy trình và bảo đảm mọi máy chủ cùng sử dụng phiên bản mới nhất. Việc chỉ sao chép một token mới vào cấu hình thường giải quyết tạm thời nhưng dễ khiến lỗi lặp lại.
Nội dung chính
Invalid token 18005 là gì trong Zalo API?
Invalid token 18005 là phản hồi cho biết máy chủ Zalo không chấp nhận thông tin xác thực được gửi kèm request. API có thể nhận được chuỗi token nhưng không xác minh được, hoặc token không còn đủ điều kiện để truy cập tài nguyên đang yêu cầu.
Thông báo có thể nằm trong JSON cùng mã lỗi và mô tả invalid token. Tên trường phản hồi có thể khác giữa từng nhóm API, nhưng bản chất vẫn là request bị từ chối trước khi nghiệp vụ chính được xử lý.
Một token hợp lệ cần đáp ứng gì?
Access token cần còn thời hạn, được cấp cho đúng ứng dụng, đúng người dùng hoặc OA, có phạm vi quyền phù hợp và chưa bị thu hồi. Token cũng phải được đặt đúng vị trí theo yêu cầu của endpoint, chẳng hạn trong header hoặc tham số xác thực tương ứng.
Vì vậy, Invalid token 18005 không luôn có nghĩa chuỗi token bị gõ sai. Token có thể đúng về ký tự nhưng sai ngữ cảnh, ví dụ token của ứng dụng thử nghiệm được dùng cho môi trường production, hoặc token người dùng được gửi đến API chỉ chấp nhận token của OA.
Nguyên nhân phổ biến gây lỗi 18005
Nguyên nhân thường gặp nhất là access token đã hết hạn nhưng ứng dụng vẫn lấy giá trị cũ từ cơ sở dữ liệu, cache, biến môi trường hoặc kho bí mật. Nếu hệ thống không lưu thời điểm hết hạn, lỗi thường chỉ được phát hiện khi request thực tế thất bại.
Invalid token 18005 cũng có thể xuất hiện sau khi refresh thành công nhưng một worker khác vẫn giữ token cũ trong bộ nhớ. Khi đó, lỗi xảy ra ngắt quãng: một số request thành công, một số request thất bại tùy máy chủ xử lý.
Dùng sai loại token hoặc sai chủ thể
Zalo có nhiều luồng cấp quyền phục vụ đăng nhập, ứng dụng, Official Account và các dịch vụ liên quan. Mỗi token gắn với một chủ thể và mục đích cụ thể. Dùng token từ luồng này cho endpoint thuộc luồng khác có thể bị từ chối dù token chưa hết hạn.
Nên lưu rõ loại token, app ID, OA ID hoặc user ID đi kèm. Không nên đặt mọi giá trị vào một biến chung như ZALO_TOKEN, vì tên mơ hồ dễ khiến lập trình viên lấy nhầm token khi mở rộng hệ thống.
Token không thuộc app ID hiện tại
Access token thường gắn với ứng dụng đã cấp nó. Nếu dự án có app riêng cho development, staging và production, việc dùng nhầm token giữa các môi trường là nguyên nhân điển hình của Invalid token 18005.
Invalid token 18005 cũng có thể phát sinh sau khi đổi app ID hoặc app secret nhưng dữ liệu cũ chưa được làm sạch. Token được cấp theo ứng dụng cũ không nên mặc định là có thể tiếp tục dùng hoặc refresh bằng thông tin của ứng dụng mới.
Token bị cắt, thêm ký tự hoặc thu hồi
Chuỗi token có thể bị cắt do cột cơ sở dữ liệu quá ngắn, bị thêm dấu nháy, khoảng trắng, ký tự xuống dòng hoặc tiền tố không đúng. Một file cấu hình có thể chứa giá trị đúng, nhưng mã đọc biến môi trường lại giữ cả dấu nháy bao quanh.
Token cũng có thể mất hiệu lực khi người dùng hủy cấp quyền, quản trị viên thay đổi liên kết OA, ứng dụng bị điều chỉnh cấu hình hoặc bộ token mới đã thay thế bộ cũ. Nếu refresh token cũng không còn hợp lệ, hệ thống phải thực hiện lại luồng ủy quyền.
Quy trình kiểm tra Invalid token 18005
Trước hết, xác định endpoint đang gọi và loại token mà endpoint yêu cầu. Sau đó đối chiếu token với app ID, OA hoặc người dùng tương ứng. Đây là bước quan trọng vì một token còn hạn vẫn có thể bị từ chối nếu sai chủ thể.
Tiếp theo, kiểm tra thời điểm cấp, giá trị expires_in hoặc thời điểm hết hạn đã lưu. Không nên hardcode một thời lượng cố định, vì cách cấp và chính sách token có thể khác giữa từng sản phẩm hoặc thay đổi theo thời gian.
Danh sách kiểm tra nên gồm:
- Request có gửi đến đúng endpoint và đúng môi trường hay không.
- Token có rỗng, bị cắt ngắn, có khoảng trắng hoặc ký tự xuống dòng không.
- App ID của token có trùng với app ID đang chạy không.
- Token có thuộc đúng OA hoặc đúng người dùng không.
- Thời điểm hiện tại đã vượt thời điểm hết hạn chưa.
- Lần refresh gần nhất có trả về token mới không.
- Cache và các worker đã nhận phiên bản token mới chưa.
- Refresh token có còn hợp lệ và thuộc cùng ứng dụng không.
- Request retry có thực sự dùng token mới không.
Khi điều tra Invalid token 18005, không nên ghi toàn bộ access token, refresh token hoặc app secret vào log. Chỉ cần lưu mã lỗi, endpoint, môi trường, app ID đã che bớt, chủ thể liên quan, thời điểm hết hạn và vài ký tự cuối của token để đối chiếu.
Cách làm mới token và thử lại request
Nếu access token hết hạn nhưng refresh token còn hợp lệ, backend cần gọi endpoint làm mới theo đúng phương thức, tham số và cơ chế xác thực của luồng đang dùng. App ID và app secret phải lấy từ kho bí mật an toàn, không đặt trực tiếp trong mã nguồn hoặc gửi xuống trình duyệt.
Sau khi nhận phản hồi thành công, hệ thống nên lưu access token mới, thời điểm hết hạn mới và refresh token mới nếu phản hồi có cung cấp. Việc lưu nên diễn ra trong cùng một giao dịch để tránh trạng thái access token mới đi kèm refresh token cũ.
Chống refresh đồng thời
Trong hệ thống nhiều worker, nhiều request có thể cùng nhận Invalid token 18005 rồi đồng thời gọi refresh. Tiến trình đầu lưu bộ token mới, trong khi tiến trình sau có thể ghi đè bằng dữ liệu không còn phù hợp hoặc làm refresh token cũ mất hiệu lực.
Giải pháp là dùng distributed lock, mutex, hàng đợi hoặc cơ chế so sánh phiên bản trong cơ sở dữ liệu. Chỉ một tiến trình được phép làm mới; các tiến trình còn lại chờ rồi đọc lại token từ nguồn dữ liệu trung tâm.
Retry đúng một lần
Sau khi refresh thành công, ứng dụng có thể gửi lại request ban đầu đúng một lần bằng token mới. Không nên retry vô hạn vì nguyên nhân có thể là sai app, sai loại token, sai endpoint hoặc refresh token đã bị thu hồi.
Luồng an toàn là: nhận Invalid token 18005, kiểm tra token đang dùng có phải phiên bản mới nhất không, refresh khi cần, cập nhật cache rồi retry một lần. Nếu vẫn lỗi, dừng request, ghi log có cấu trúc và phát cảnh báo cho đội vận hành.
Khi nào cần cấp quyền lại?
Nếu refresh token hết hạn, bị thu hồi, thuộc sai app hoặc đã được thay thế, ứng dụng không thể tự khôi phục bằng cách gọi refresh liên tục. Người dùng hoặc quản trị viên cần thực hiện lại luồng cấp quyền để hệ thống nhận bộ token mới.
Với OA, hãy kiểm tra thêm trạng thái liên kết giữa ứng dụng và OA, quyền của tài khoản quản trị và scope đã được chấp thuận. Sau khi cấp lại, cần xóa cache token cũ để tránh Invalid token 18005 quay trở lại trên một số máy chủ.
Kiểm tra app ID, app secret và request
Khi xử lý Invalid token 18005, hãy đối chiếu cấu hình ở trang quản lý ứng dụng, biến môi trường của dịch vụ và bản ghi token trong cơ sở dữ liệu. Chỉ một nơi giữ app ID cũ hoặc secret cũ cũng có thể làm quá trình refresh thất bại.
Kiểm tra cách truyền token
Không nên mặc định mọi endpoint đều dùng Authorization: Bearer. Từng nhóm API có thể quy định vị trí và tên trường khác nhau. Cách an toàn là xây dựng client riêng cho từng nhóm API và viết test cho cấu trúc request.
Cần bảo đảm thư viện HTTP không thêm dấu nháy, không mã hóa lại token và không gửi các giá trị undefined, null hoặc chuỗi rỗng. Có thể loại bỏ khoảng trắng ở đầu và cuối, nhưng nếu token có độ dài bất thường thì nên dừng request thay vì âm thầm gửi.
Bảo vệ app secret
Nếu Invalid token 18005 xuất hiện ngay sau khi đổi secret, cần kiểm tra dịch vụ nào đã nạp cấu hình mới, dịch vụ nào còn dùng giá trị cũ và luồng refresh có yêu cầu secret mới hay không. Khởi động lại toàn bộ hệ thống mà không kiểm tra phiên bản cấu hình có thể chỉ che giấu nguyên nhân.
Cách xử lý theo từng tình huống thực tế
Nếu Invalid token 18005 xuất hiện ngay sau khi triển khai, ưu tiên kiểm tra biến môi trường, tên secret, app ID và quá trình nạp cấu hình vào container. Nhiều sự cố tưởng là lỗi Zalo thực tế đến từ production đang dùng giá trị của staging.
Nếu Invalid token 18005 chỉ xuất hiện sau một thời gian chạy ổn định, khả năng cao token đã hết hạn hoặc lịch refresh không hoạt động. Hãy kiểm tra phản hồi của lần refresh gần nhất, thời điểm hết hạn và việc lưu bộ token mới.
Nếu lỗi xảy ra ngẫu nhiên trên một phần request, hãy kiểm tra cache phân tán, nhiều máy chủ sử dụng token khác phiên bản hoặc refresh đồng thời. Đây là dấu hiệu rõ ràng cho thấy quản lý vòng đời token chưa được đồng bộ.
Nếu lỗi chỉ xảy ra với một OA hoặc một người dùng, cần kiểm tra ánh xạ chủ thể, trạng thái cấp quyền và scope. Không nên lấy một token dùng chung cho mọi tài khoản khi API yêu cầu token riêng.
Kết luận về Invalid token 18005
Invalid token 18005 cho biết Zalo API không chấp nhận token đi kèm request, thường do hết hạn, sai loại, sai ứng dụng, sai chủ thể, bị thu hồi hoặc bị truyền sai định dạng. Cách khắc phục hiệu quả là kiểm tra toàn bộ ngữ cảnh của token thay vì chỉ thay chuỗi mới thủ công cùng với htlandholding.
Một hệ thống ổn định cần lưu thời điểm hết hạn, chủ động refresh, khóa thao tác làm mới đồng thời, cập nhật cả access token và refresh token mới, retry có giới hạn và bảo vệ app secret. Khi các bước này được tự động hóa, lỗi token sẽ dễ phát hiện, ít tái diễn và không làm gián đoạn lâu việc tích hợp Zalo.
Vương Minh – người dẫn dắt và đứng sau sự thành công của ZALO Web cùng với đội ngũ kĩ sư ưu tú nhất. Với khát vọng tạo ra một sản phẩm công nghệ “Make in Vietnam” đủ sức cạnh tranh sòng phẳng với các đối thủ quốc tế, ông Khải cùng các cộng sự tại Zalo Group đã không ngừng cải tiến để Zalo không chỉ là app nhắn tin mà còn là một hệ sinh thái làm việc đa nền tảng. Zalo Web chính là minh chứng cho triết lý đó: tinh gọn, tốc độ và thấu hiểu sâu sắc thói quen của người dùng Việt.