Mỗi lần gọi API đều nhận về một con số ba chữ số, và con số đó đã nói được một nửa nguyên nhân: nhóm bốn trăm thường là yêu cầu của bạn có vấn đề, nhóm năm trăm thường là máy chủ bên kia gặp sự cố. Biết đọc vài mã thường gặp, bạn phân biệt được lúc nào cần sửa luồng, lúc nào chỉ cần chờ rồi chạy lại.
Bài này là bảng tra cho người dùng công cụ kết nối kéo thả, không phải tài liệu kỹ thuật đầy đủ. Mỗi mã đi kèm nguyên nhân hay gặp trong luồng tự động thực tế và việc nên làm tiếp. Phần sau bàn về chạy lại tự động, vì chạy lại sai cách có thể tạo bản ghi trùng hoặc khiến bạn bị chặn lâu hơn.
Đọc mã trạng thái theo nhóm
Mã trạng thái chia theo chữ số đầu. Nhóm hai trăm là thành công: 200 nghĩa là ổn, 201 là đã tạo mới, 204 là ổn nhưng không có nội dung trả về, thường gặp khi xoá. Nhóm ba trăm là chuyển hướng, ít gặp trong luồng tự động, nhưng nếu thấy thì thường do bạn dùng địa chỉ cũ và API đã dời sang địa chỉ mới.
Nhóm bốn trăm là lỗi phía yêu cầu: thiếu khoá, sai quyền, sai địa chỉ, thiếu trường, gọi quá nhanh. Đây là loại bạn sửa được, và chạy lại y hệt sẽ ra y hệt lỗi, trừ mã 429 là trường hợp đặc biệt. Nhóm năm trăm là lỗi phía máy chủ: bên kia đang trục trặc, quá tải, hoặc đang bảo trì. Loại này thường tự hết sau một lúc, chạy lại sau vài phút có thể thành công.
Trong công cụ kéo thả, mã trạng thái thường nằm ở chi tiết lần chạy của bước gọi, cạnh phần tiêu đề và nội dung phản hồi. Có công cụ chỉ hiện dòng báo bước thất bại ở ngoài danh sách, phải bấm vào lần chạy rồi mở bước bị đỏ mới thấy con số. Nếu luồng có nhiều bước gọi API, ghi nhớ bước nào gọi tới ứng dụng nào, vì cùng mã 401 ở bước bảng tính và ở bước dịch vụ AI có cách xử lý khác nhau.
Đừng chỉ nhìn con số. Đi kèm mã thường có một khối nội dung giải thích, đôi khi chỉ đúng trường nào sai. Trong công cụ kéo thả, mở chi tiết lần chạy bị lỗi, tìm phần phản hồi, đọc câu mô tả trước khi đoán.
Bảng tra nhanh các mã hay gặp
Nguyên nhân trong cột giữa là những ca hay gặp nhất với luồng kéo thả, không phải mọi khả năng.
| Mã | Nghĩa và nguyên nhân hay gặp | Việc nên làm |
|---|---|---|
| 400 | Yêu cầu không hợp lệ: JSON vỡ cấu trúc, thiếu trường bắt buộc, giá trị sai định dạng như ngày tháng hay email | Đọc mô tả lỗi, kiểm dữ liệu từ bước trước, thêm bước định dạng hoặc giá trị mặc định |
| 401 | Chưa xác thực: thiếu khoá, khoá sai, khoá đã bị thu hồi, mã truy cập hết hạn | Kiểm khoá trong ô xác thực, kết nối lại tài khoản trong công cụ, tạo khoá mới nếu cần |
| 403 | Đã xác thực nhưng không có quyền: khoá thiếu phạm vi, tài khoản không có vai trò, tính năng không có trong gói | Xem lại phạm vi quyền của khoá và vai trò tài khoản; không nâng thành quyền quản trị cho nhanh |
| 404 | Không tìm thấy: sai đường dẫn điểm cuối, mã bản ghi không tồn tại hoặc đã bị xoá | Kiểm địa chỉ và phiên bản API; kiểm mã bản ghi lấy từ bước trước có đúng không |
| 409 | Xung đột: bản ghi đã tồn tại, hoặc đang bị sửa bởi thao tác khác | Thêm bước kiểm tồn tại trước khi tạo; chuyển sang cập nhật nếu đã có |
| 422 | Dữ liệu đúng cấu trúc nhưng không hợp lệ theo luật của ứng dụng, như số lượng âm, email trùng | Đọc mô tả, sửa dữ liệu nguồn hoặc thêm điều kiện lọc |
| 429 | Gọi quá nhiều trong thời gian ngắn, vượt giới hạn lượt gọi | Chờ theo thời gian bên kia gợi ý rồi thử lại; giãn nhịp hoặc gom yêu cầu |
| 500, 502, 503, 504 | Lỗi phía máy chủ, cổng trung gian, quá tải hoặc bảo trì, hết thời gian chờ | Chạy lại sau vài phút; nếu kéo dài, xem trang trạng thái của dịch vụ |
Không phải API nào cũng dùng mã đúng chuẩn. Có dịch vụ trả 200 kèm một trường báo lỗi trong nội dung, có dịch vụ trả 400 cho mọi loại lỗi. Đọc phần lỗi trong tài liệu API của chính dịch vụ bạn đang gọi.
401 và 403: hai lỗi quyền hay bị nhầm
401 là bên kia không biết bạn là ai. Giống đưa phiếu gọi món mà không có thẻ nhân viên. Nguyên nhân thường gặp nhất trong luồng kéo thả là kết nối tài khoản đã hết hạn, nhất là với kiểu đăng nhập rồi bấm cho phép, vì mã truy cập có hạn dùng và đôi khi việc tự làm mới thất bại. Kết nối lại tài khoản trong công cụ thường giải quyết được.
403 là bên kia biết bạn là ai nhưng không cho làm việc này. Khoá chỉ có quyền đọc mà luồng định ghi, tài khoản dùng cho luồng có vai trò nhân viên mà việc cần vai trò quản lý, hoặc tính năng chỉ có ở gói cao hơn. Chạy lại không giúp gì.
Đừng chữa 403 bằng quyền quản trị. Cách nhanh nhất để hết lỗi là tạo khoá toàn quyền hoặc kết nối bằng tài khoản chủ, và đó là cách tệ nhất. Hãy thêm đúng quyền còn thiếu, ghi lại lý do trong sổ theo dõi khoá.
Khi 401 xuất hiện đồng loạt. Nếu nhiều luồng cùng báo 401 một lúc, có thể ai đó vừa đổi mật khẩu tài khoản dùng để kết nối, vừa thu hồi khoá, hoặc nhân viên sở hữu tài khoản đó vừa bị khoá khi nghỉ việc. Đây là lý do nên dùng tài khoản riêng cho tự động hoá thay vì tài khoản cá nhân.
429: bị chặn vì gọi quá nhanh
Mã 429 nghĩa là bạn đã vượt giới hạn lượt gọi trong một khoảng thời gian. Mỗi API đặt giới hạn riêng, có nơi tính theo giây, có nơi theo phút, theo ngày, hoặc theo lượng dữ liệu xử lý như các dịch vụ mô hình AI tính theo lượng chữ mỗi phút. Phản hồi 429 thường kèm một tiêu đề cho biết nên chờ bao lâu trước khi thử lại, phổ biến nhất là tiêu đề Retry-After.
Trong luồng kéo thả, 429 hay xảy ra ở ba chỗ: vòng lặp qua danh sách dài mà không có bước chờ, nhiều luồng cùng dùng một khoá và cùng chạy đúng một giờ, và lần chạy bù sau khi luồng bị tắt một thời gian, dồn cả trăm sự kiện xử lý cùng lúc. Cách chữa tương ứng: thêm bước chờ trong vòng lặp, lệch giờ chạy các luồng, và chia việc chạy bù thành nhiều đợt.
Với dịch vụ AI, 429 còn có thể đến từ việc bạn đã chạm hạn mức chi tiêu hoặc hạn mức tài khoản, không chỉ do gọi nhanh. Đọc kỹ mô tả lỗi để phân biệt; nếu là hạn mức tiền, chờ không giúp gì, phải xem lại cài đặt tài khoản.
Đừng tìm cách lách giới hạn bằng nhiều tài khoản hay nhiều khoá. Hầu hết điều khoản dịch vụ cấm việc này, và bị phát hiện có thể dẫn tới khoá cả tài khoản chính. Nếu việc thật sự cần nhiều lượt hơn, hỏi nhà cung cấp về gói phù hợp hoặc điểm cuối xử lý hàng loạt.
Chạy lại tự động sao cho không gây hại
Phần lớn công cụ kết nối cho bật chạy lại khi bước thất bại. Bật thì tiện, nhưng cần cài đúng.
- Chỉ chạy lại tự động cho lỗi tạm thời: 429 và nhóm năm trăm, cùng lỗi hết thời gian chờ. Các lỗi 400, 401, 403, 404 chạy lại y hệt chỉ tốn lượt.
- Đặt khoảng chờ tăng dần giữa các lần thử, ví dụ một phút, năm phút, mười lăm phút, thay vì thử liên tục. Nhiều công cụ gọi đây là lùi dần.
- Giới hạn số lần thử, ba tới năm lần là đủ cho phần lớn trường hợp, rồi chuyển sang báo lỗi cho người.
- Với bước tạo bản ghi, gửi tiền hay gửi tin cho khách, trước khi thử lại hãy kiểm xem lần trước thực sự đã thất bại chưa. Lỗi hết thời gian chờ có thể xảy ra sau khi bên kia đã tạo bản ghi xong.
- Nếu API hỗ trợ khoá chống trùng, thường gọi là idempotency key, dùng một giá trị cố định như mã đơn cho mỗi yêu cầu tạo, để bên kia tự bỏ qua yêu cầu lặp.
- Ghi mọi lần thất bại cuối cùng vào bảng nhật ký kèm mã lỗi và dữ liệu đầu vào đã che thông tin cá nhân, để có thể chạy bù bằng tay.
Chạy lại đúng cách biến phần lớn lỗi tạm thời thành chuyện không ai phải để ý. Chạy lại sai cách thì biến một lỗi nhỏ thành ba đơn trùng và một khách nhận ba tin nhắn giống nhau.
Nhờ AI đọc lỗi và khi nào cần người khác
Khi gặp một mã lỗi kèm câu mô tả khó hiểu, chatbot AI là trợ thủ tốt. Câu lệnh mẫu: Luồng tự động của mình gọi API tạo đơn và nhận mã 422 với nội dung lỗi dưới đây. Giải thích lỗi bằng lời thường, liệt kê ba nguyên nhân có thể nhất, và cho biết nên kiểm gì trước. Dán kèm phần nội dung lỗi và phần dữ liệu đã gửi, sau khi đã xoá khoá và thay thông tin khách bằng giá trị giả.
AI giải thích khá chính xác ý nghĩa chung của mã, nhưng không biết luật riêng của ứng dụng bạn dùng. Nếu nó đoán một trường phải theo định dạng nào đó, đối chiếu với tài liệu API. Nếu nó gợi ý sửa bằng cách nâng quyền, cân nhắc kỹ như đã nói ở phần 403.
Có những lúc nên dừng tự sửa: lỗi nhóm năm trăm kéo dài nhiều giờ dù trang trạng thái của dịch vụ báo bình thường, lỗi chỉ xảy ra với một số bản ghi mà không tìm ra quy luật, hoặc lỗi trên luồng liên quan tới tiền. Lúc đó, gom các lần lỗi kèm mã, thời gian, mô tả, rồi gửi cho bộ phận hỗ trợ của dịch vụ hoặc người có kinh nghiệm. Gửi càng đủ thông tin, họ trả lời càng nhanh.
Câu hỏi thường gặp
Mã 200 có chắc là mọi thứ đã ổn không?
Thường là ổn, nhưng không chắc tuyệt đối. Có API trả 200 kèm trường báo lỗi trong nội dung, và có trường hợp ghi thành công nhưng dữ liệu sai do ánh xạ nhầm. Kiểm kết quả trong ứng dụng đích ở những lần chạy đầu.
Luồng chạy tốt nhiều tháng bỗng báo 401 là vì sao?
Hay gặp nhất là kết nối tài khoản hết hạn, mật khẩu tài khoản bị đổi, hoặc khoá bị thu hồi khi rà soát. Kết nối lại hoặc cập nhật khoá mới, rồi xem có nên chuyển sang tài khoản riêng cho tự động hoá.
Lỗi 404 khi bản ghi rõ ràng vẫn còn thì sao?
Kiểm mã bản ghi lấy từ bước trước có đúng không, có bị thừa khoảng trắng hay bị đổi thành số làm mất số 0 đầu không. Kiểm cả phiên bản API trong địa chỉ, vì điểm cuối có thể đã đổi đường dẫn.
Có nên bật chạy lại tự động cho mọi bước không?
Không. Chỉ bật cho lỗi tạm thời như 429 và nhóm năm trăm. Với bước tạo bản ghi hay gửi tin cho khách, phải có cách chống trùng trước khi bật, nếu không sẽ gửi lặp.
Trang trạng thái của dịch vụ là gì?
Nhiều dịch vụ có một trang công khai báo tình trạng hoạt động và sự cố đang xảy ra. Khi gặp lỗi nhóm năm trăm, xem trang đó trước khi mất công dò luồng của mình.
Ghi nhật ký lỗi có cần lưu dữ liệu khách không?
Chỉ lưu đủ để chạy bù và tra cứu, như mã đơn, thời gian, mã lỗi. Che hoặc bỏ tên, số điện thoại, địa chỉ khách khỏi nhật ký, và đặt thời hạn xoá nhật ký cũ.