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.

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.

Bảng mã lỗi API thường gặp trong n8n
| Mã / nhóm lỗi | Dấu hiệu thường gặp | Kiểm tra và hướng xử lý |
|---|---|---|
| 400 Bad Request | Tham 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 Unauthorized | Thiếu/sai credential, token hết hạn | Kiểm header, khóa và đúng kiểu xác thực; đăng nhập lại nếu cần |
| 403 Forbidden | Máy chủ từ chối yêu cầu | Kiểm scope, vai trò, gói, IP và chính sách truy cập |
| 404 Not Found | Không tìm thấy endpoint/tài nguyên | Kiểm phiên bản URL, đường dẫn và ID |
| 405 Method Not Allowed | Endpoint không nhận method đang dùng | Đổi GET/POST/PUT… theo tài liệu |
| 413 Payload Too Large | Body hoặc file quá lớn | Giả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 đúng | Kiể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ạy | Kiểm dấu ngoặc/nháy/phẩy và expression |
| 429 Too Many Requests | Vượt rate limit hoặc quota | Đọc response/header, giảm tốc độ; chờ theo Retry-After nếu có |
| 500 Internal Server Error | Sự 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 / 504 | Gateway, quá tải, bảo trì hoặc timeout upstream | Giã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ận | Kiểm dịch vụ và network; localhost trong container là chính container |
| Timeout / ETIMEDOUT | Không nhận response trong thời gian chờ | Kiểm mạng, firewall và timeout trước khi tăng ngưỡng |
| TLS / SSL | Khô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.

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.

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.

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.

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.

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:

- 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.