Phan Đông GiangPhan Đông Giang
Tất cả bài viết

Chẩn đoán lỗi API trong n8n: mã HTTP, kết nối và retry

Tra lỗi 400, 401, 403, 404, 429, 5xx; đọc Output và execution rồi cấu hình các nhánh xử lý lỗi phù hợp.

Chẩn đoán lỗi API trong n8n: mã HTTP, kết nối và retry

Một request API thất bại có thể trả mã HTTP hoặc dừng trước khi nhận được phản hồi. Trong n8n, hãy đọc cả mã, thông báo chi tiết và dữ liệu đã gửi. Lỗi request, lỗi máy chủ và lỗi đường truyền cần cách xử lý khác nhau; retry liên tục không giải quyết được tất cả.

Bảng tra này hỗ trợ workflow dùng HTTP Request. Nếu chưa cấu hình được một request chuẩn, bắt đầu với thêm API vào n8n; nếu gặp vấn đề về bí mật, đọc bảo mật credential.

Lỗi API là gì?

Khi máy chủ nhận được request, mã trạng thái HTTP giúp mô tả kết quả: nhóm 4xx thường cho biết yêu cầu không thể được thực hiện do xác thực, quyền, địa chỉ hoặc điều kiện phía client; nhóm 5xx biểu thị sự cố phía máy chủ xử lý. Còn DNS, từ chối kết nối, timeout hay lỗi chứng chỉ có thể xảy ra trước khi có HTTP response.

Hãy phân nhóm trước khi sửa: kiểm request với 4xx, kiểm trạng thái dịch vụ và retry có kiểm soát với 5xx, kiểm mạng/cổng/TLS với lỗi không có mã HTTP. Một số API dùng mã không nhất quán, nên vẫn cần đọc nội dung response.

Cây chẩn đoán lỗi API trong n8n: mở panel OUTPUT của node lỗi, nếu có mã 4xx thì kiểm tham số (400, 415), xác thực (401), quyền (403), URL (404), tốc độ (429); nếu mã 5xx thì lỗi máy chủ API, bật Retry On Fail; nếu không có mã thì là lỗi kết nối ECONNREFUSED, timeout hoặc SSL
Minh họa được biên tập lại cho PHAN ĐÔNG GIANG; giao diện thực tế có thể khác.

Bảng mã lỗi API thường gặp trong n8n

Mã / nhóm lỗiDấu hiệu thường gặpKiểm tra và hướng xử lý
400 Bad RequestTham số hoặc body không được chấp nhậnĐối chiếu tên, kiểu dữ liệu, mảng và giá trị với tài liệu
401 UnauthorizedThiếu/sai credential, token hết hạnKiểm header, khóa và đúng kiểu xác thực; đăng nhập lại nếu cần
403 ForbiddenMáy chủ từ chối yêu cầuKiểm scope, vai trò, gói, IP và chính sách truy cập
404 Not FoundKhông tìm thấy endpoint/tài nguyênKiểm phiên bản URL, đường dẫn và ID
405 Method Not AllowedEndpoint không nhận method đang dùngĐổi GET/POST/PUT… theo tài liệu
413 Payload Too LargeBody hoặc file quá lớnGiảm kích thước, chia lô theo giới hạn API
415 Unsupported Media TypeĐịnh dạng nội dung không đúngKiểm Content-Type, JSON/form-data và trường binary
JSON không hợp lệLỗi cú pháp trước khi request chạyKiểm dấu ngoặc/nháy/phẩy và expression
429 Too Many RequestsVượt rate limit hoặc quotaĐọc response/header, giảm tốc độ; chờ theo Retry-After nếu có
500 Internal Server ErrorSự cố khi dịch vụ xử lýKiểm trang status; retry có giới hạn nếu thao tác an toàn
502 / 503 / 504Gateway, quá tải, bảo trì hoặc timeout upstreamGiãn khoảng retry và báo nhà cung cấp nếu kéo dài
ECONNREFUSEDĐịa chỉ/cổng không có dịch vụ tiếp nhậnKiểm dịch vụ và network; localhost trong container là chính container
Timeout / ETIMEDOUTKhông nhận response trong thời gian chờKiểm mạng, firewall và timeout trước khi tăng ngưỡng
TLS / SSLKhông xác minh được chứng chỉSửa hostname, hạn chứng chỉ và certificate chain

401 và 403 không tương đương. Với 401, ưu tiên thông tin xác thực; với 403, ưu tiên quyền và chính sách từ chối. Máy chủ có thể từ chối ngay cả khi key hợp lệ, nên thay key ngẫu nhiên chưa chắc giúp ích.

Ví dụ: đọc lỗi trên một workflow gọi API thời tiết

Workflow minh họa gọi OpenWeatherMap rồi xử lý dữ liệu và ghi vào Google Sheets: Manual Trigger → HTTP Request → Code → Google Sheets. Bạn có thể áp dụng cùng cách đọc lỗi cho một API khác.

Workflow mẫu trong n8n: Manual Trigger, HTTP Request gọi API OpenWeatherMap, node Code xử lý JSON và Google Sheets ghi dòng mới

Lỗi 401: thiếu hoặc sai API key

Nếu Output báo Authorization failed và phản hồi chứa Invalid API key, rà lại key, vị trí truyền key và quyền sử dụng API. Với OpenWeatherMap, có thể lưu khóa bằng credential Query Auth có Name là appid thay vì gõ khóa thẳng vào URL.

Node HTTP Request trong n8n báo lỗi 401 Authorization failed, Full message Invalid API key từ OpenWeatherMap, API key trong URL đã được che

Lỗi 404: sai endpoint hoặc tham số

Một URL sai, phiên bản endpoint đã thay đổi hoặc giá trị tìm kiếm không tồn tại có thể dẫn đến 404. Trong ví dụ thời tiết, kiểm đường dẫn /data/2.5/weather và tên thành phố; q=hanoi,vn giúp định vị rõ hơn một tên thành phố không kèm quốc gia.

Node HTTP Request trong n8n báo lỗi 404 The resource you are requesting could not be found khi gọi OpenWeatherMap với tên thành phố sai, API key đã được che

Lỗi 429: gọi API quá nhanh

Khi nhiều item cùng gửi request hoặc lịch chạy quá dày, mở Options → Batching để chia lô và thêm khoảng nghỉ. Ví dụ một item mỗi 1.000 ms tương đương khoảng một request/giây, nhưng không phải hạn mức mặc định của mọi API. Kiểm cả quota theo ngày và thông báo của provider.

Node HTTP Request trong n8n báo lỗi 429 The service is receiving too many requests from you, Full message gợi ý giãn request bằng batching trong Options

Lỗi 500: máy chủ API gặp sự cố

500 cho biết dịch vụ không hoàn thành việc xử lý. Kiểm status page và thử lại có giới hạn nếu phù hợp. Với request ghi/tạo mới, cần xác định thao tác đã thực hiện hay chưa trước khi retry để tránh trùng dữ liệu.

Node HTTP Request trong n8n báo lỗi 500 The service was not able to process your request, Internal Server Error từ phía dịch vụ API

Lỗi SSL: chứng chỉ của API không hợp lệ

Chứng chỉ hết hạn, sai hostname hoặc thiếu chuỗi trung gian đều có thể khiến TLS thất bại. Kiểm chứng chỉ phía API và đồng hồ hệ thống; đừng bật Ignore SSL Issues như giải pháp lâu dài cho một endpoint công khai.

Có thể kiểm certificate chain bằng công cụ chẩn đoán TLS hoặc trình duyệt, nhưng cũng phải kiểm từ môi trường máy chủ n8n vì đường mạng và trust store có thể khác máy cá nhân.

Cách xem chi tiết lỗi API trong n8n

Trong lần chạy thử, mở Output của node thất bại và xem Error details. Với workflow chạy tự động, mở Executions để tìm đúng lần chạy và item gây lỗi. Trước khi chia sẻ log, luôn kiểm xem URL, header và body có chứa bí mật hay dữ liệu cá nhân không.

  • Output / Error details: đọc mã, Full message và request thực tế thay vì chỉ dòng cảnh báo ngắn.
  • Include Response Headers and Status: bật khi cần xem Content-Type, mã và header quota.
  • Never Error: dùng khi chủ động xử lý response khác 2xx ở node sau; phải có nhánh phân biệt thành công/thất bại.
  • Executions: tìm đúng lần chạy lỗi khi workflow chạy tự động.
  • Debug in editor: dùng dữ liệu từ execution cũ để tái hiện, nhưng cân nhắc tác dụng phụ trước khi chạy lại các node ghi dữ liệu.

Cách tự xử lý lỗi API trong workflow

Workflow chạy tự động nên có cơ chế phản ứng khi request thất bại. Ba lớp thường dùng là thử lại tại node, tách đầu ra lỗi và một workflow chuyên cảnh báo:

Luồng xử lý một request lỗi trong n8n: lỗi 429, 5xx, timeout đi qua Retry On Fail, lỗi 401, 403, 404 không thử lại mà cần sửa credential hoặc URL; nếu vẫn lỗi, node có On Error Continue đưa item sang nhánh lỗi để các item khác chạy tiếp, nếu không thì execution thất bại và Error workflow bắt đầu bằng Error Trigger gửi cảnh báo qua Telegram, email
Minh họa được biên tập lại cho PHAN ĐÔNG GIANG; giao diện thực tế có thể khác.
  • Retry On Fail: đặt Max Tries và Wait Between Tries cho sự cố tạm thời; không lặp một request chắc chắn sai khóa hoặc endpoint.
  • On Error → Continue (using error output): nhận lỗi ở nhánh riêng để ghi log, cảnh báo hoặc trả kết quả dự phòng; theo dõi cả item thất bại.
  • Error workflow: tạo workflow với Error Trigger rồi gán trong Settings của workflow chính. Stop and Error có thể chủ động báo một điều kiện nghiệp vụ là thất bại.

Node HTTP Request có bị lỗi CORS không?

CORS được trình duyệt thực thi khi trang web gọi sang origin khác. HTTP Request chạy ở máy chủ n8n nên không chịu chính sách CORS của trình duyệt. Thêm Access-Control-Allow-Origin vào request không làm server n8n vượt qua một lỗi API.

CORS có thể liên quan ở chiều trang web trên trình duyệt gọi webhook n8n. Khi đó cấu hình Allowed Origins của Webhook và phản hồi phía server theo tài liệu Webhook; đây là tình huống khác với node HTTP Request gọi ra ngoài.

Đọc tiếp theo từng lỗi

Nếu cần điều tra sâu hơn, tách hồ sơ theo nhóm xác thực, quyền dịch vụ, kết nối hoặc hiệu năng. Những thông tin sau giúp bạn chọn bước tiếp theo:

  • Xác thực: đối chiếu nơi truyền khóa và hạn token; không đưa key vào log gửi hỗ trợ.
  • Google và các dịch vụ OAuth: kiểm scope, quyền tài nguyên và trạng thái cấp quyền.
  • Timeout: đo thời gian từ máy chủ n8n tới API, rà firewall và giới hạn node/workflow.
  • Workflow chậm: xem số item, kích thước dữ liệu và số request thực tế trước khi tăng tài nguyên.

Sau khi sửa lỗi, gọi lại một request nhỏ theo hướng dẫn HTTP Request, xác minh dữ liệu trả về rồi mới bật lại lịch hoặc xử lý cả lô.

Những câu hỏi thường gặp

Vì sao API trả về HTML thay vì JSON?

Có thể bạn đang gọi URL trang web, bị chuyển tới màn hình đăng nhập hoặc nhận trang chặn của proxy/WAF. Đọc mã trạng thái, Content-Type và redirect; kiểm endpoint API trước khi cố parse HTML thành JSON.

Lỗi API do n8n hay do dịch vụ bên kia?

Mã trạng thái chỉ là dấu hiệu ban đầu. Gửi lại cùng request đã che bí mật bằng một công cụ thử API phù hợp để so sánh. Nếu cùng dữ liệu đều lỗi, hãy điều tra endpoint, quyền hoặc dịch vụ; nếu chỉ n8n lỗi, đối chiếu request và đường mạng thực tế.

N8n Cloud và n8n tự host có gặp lỗi API khác nhau không?

Ý nghĩa mã HTTP không thay đổi. Điểm khác thường nằm ở đường mạng: localhost bên trong Docker không trỏ tới host, còn dịch vụ chỉ ở LAN của bạn có thể không truy cập được từ n8n Cloud. Dùng kết nối mạng riêng hoặc phương án truy cập được kiểm soát phù hợp.

Nên làm gì khi đã thử hết mà lỗi API vẫn còn?

Ghi mã lỗi, thời điểm, request ID nếu có và một request tái hiện đã loại bí mật. Gửi nhà cung cấp khi sự cố ở API; dùng cộng đồng n8n khi cần hỗ trợ cấu hình node. Đừng đính kèm key hoặc file workflow chưa kiểm tra.

Bộ SKILLS EDIT VIDEOBạn quay. AI edit tự động.Ủng hộ mình 1 ly cafe
Video thật. Thành quả từ bộ Skills.
Trọn bộ 8 Skills · Mua một lần, dùng trọn đời

Để AI edit.
Dành thời gian cho điều quan trọng.

Thời gian edit mỗi video
3–4 giờ5–10 phút
Ưu đãi có hạn2.199.000đXem giá hiện tạiTrọn bộ 8 Skills & video hướng dẫn

Tiết kiệm 800.000đ · Mua một lần, dùng trọn đời.

Sở hữu bộ 8 SKILLS ngay!

Nhận bộ Skills và video hướng dẫn qua email.