Lỗi API là khi yêu cầu gửi tới một API thất bại: máy chủ trả mã lỗi hoặc không trả lời kịp. Mã 4xx nghĩa là request có vấn đề (sai khóa, sai URL, gửi quá nhanh), mã 5xx là lỗi phía máy chủ API. Trong n8n, lỗi hiện ở node HTTP Request kèm mã và thông báo.
Trang này là bảng tra lỗi API cho người dùng n8n: đọc mã, đoán nguyên nhân, kiểm ở đâu, rồi đi tới bài chi tiết của từng lỗi. Tên nút và thông báo theo n8n 2.x, đối chiếu docs.n8n.io ngày 22/10/2026.
Lỗi API là gì?
Lỗi API là phản hồi cho biết một request tới API không thành công. Phản hồi gồm mã trạng thái HTTP và thường kèm nội dung mô tả lỗi. Theo RFC 9110, mã 4xx là lỗi phía client (request sai, thiếu quyền, sai địa chỉ), mã 5xx là lỗi phía máy chủ. Ngoài ra còn nhóm lỗi kết nối không có mã HTTP: máy chủ từ chối kết nối, quá thời gian chờ, lỗi chứng chỉ SSL.
Phân biệt ba nhóm này giúp quyết định đúng việc cần làm: lỗi 4xx phải sửa request, lỗi 5xx thường chờ hoặc thử lại, lỗi kết nối phải kiểm mạng, DNS, cổng, chứng chỉ.
Bảng mã lỗi API thường gặp trong n8n
Bảng dưới gom các lỗi node HTTP Request hay báo, theo trang Common issues của node HTTP Request và kinh nghiệm chạy workflow thực tế. Thông báo trong n8n lấy nguyên văn tiếng Anh để bạn dễ tìm; với mã không có thông báo riêng, n8n hiển thị nội dung lỗi của dịch vụ.
Mã / lỗi Thông báo trong n8n Nguyên nhân thường gặp Cách kiểm và sửa Bài chi tiết 400 Bad Request Bad request – please check your parameters Sai tên hoặc giá trị tham số, mảng truyền sai định dạng So tham số với tài liệu API; thử tùy chọn Array Format in Query Parameters 401 Unauthorized Authorization failed – please check your credentials Thiếu hoặc sai API key, token hết hạn, sai kiểu xác thực Dùng credential (Header Auth, Query Auth, OAuth2), kết nối lại tài khoản Lỗi 401 Unauthorized 403 Forbidden Forbidden – perhaps check your credentials Đã xác thực nhưng thiếu quyền, scope, gói dịch vụ hoặc IP bị chặn Cấp thêm quyền hoặc scope, tạo key mới đủ quyền Lỗi 401 Unauthorized (mục 401 và 403) 404 Not Found The resource you are requesting could not be found Sai endpoint, sai ID, API đã đổi phiên bản Đối chiếu URL với tài liệu API hiện hành 405 Method Not Allowed Nội dung lỗi của dịch vụ Dùng GET cho endpoint chỉ nhận POST (hoặc ngược lại) Đổi Method của node theo tài liệu 413 Payload Too Large Nội dung lỗi của dịch vụ File hoặc body vượt giới hạn của máy chủ nhận Giảm kích thước, chia nhỏ lô 415 Unsupported Media Type Nội dung lỗi của dịch vụ API cần multipart/form-data nhưng body gửi dạng khác Body Content Type = Form-Data, tham số kiểu n8n Binary File JSON không hợp lệ JSON parameter need to be an valid JSON Thiếu dấu ngoặc, dấu phẩy, dấu nháy trong body JSON Kiểm cú pháp JSON; dùng expression thì bọc cả JSON trong {{ }} 429 Too Many Requests The service is receiving too many requests from you Vượt giới hạn tốc độ của dịch vụ Options > Batching (Items per Batch, Batch Interval), Retry On Fail Lỗi Google Sheets, Drive (429 của Google) 500 Internal Server Error The service was not able to process your request Lỗi nội bộ của dịch vụ, thường tạm thời Thử lại sau, xem trang trạng thái của dịch vụ 502, 503, 504 Nội dung lỗi của cổng hoặc dịch vụ Gateway hoặc máy chủ phía sau quá tải, bảo trì, quá hạn Retry On Fail có giãn cách; báo nhà cung cấp nếu kéo dài Timeout trong n8n ECONNREFUSED Connection refused Cổng không có dịch vụ lắng nghe; trong Docker, localhost là chính container n8n Dùng host.docker.internal hoặc tên service trong Docker Compose Timeout, ETIMEDOUT Nội dung lỗi kết nối API trả lời chậm hơn Timeout của node, mạng hoặc tường lửa chặn Tăng Options > Timeout, kiểm mạng từ máy chủ n8n Timeout trong n8n Lỗi SSL Nội dung lỗi chứng chỉ Chứng chỉ của API hết hạn, sai tên miền, thiếu chứng chỉ trung gian Kiểm chứng chỉ của API; Ignore SSL Issues chỉ dùng tạm để chẩn đoán
Một lưu ý về 401 và 403: tài liệu n8n ghi thông báo 403 là “authentication failed”, nhưng theo RFC 9110, 403 là đã hiểu yêu cầu và từ chối, thường do thiếu quyền. Khi gặp 403, kiểm quyền và scope của key trước khi đổi key.
Ví dụ: đọc lỗi trên một workflow gọi API thời tiết
Workflow mẫu lấy dữ liệu thời tiết từ OpenWeatherMap, xử lý bằng node Code rồi ghi vào Google Sheets: Manual Trigger → HTTP Request → Code → Google Sheets. Mỗi lỗi dưới đây được dựng lại trên chính workflow này.
Lỗi 401: thiếu hoặc sai API key
Node HTTP Request báo “Authorization failed – please check your credentials”, Full message của OpenWeatherMap ghi “Invalid API key”. Sửa bằng credential Query Auth với Name appid thay vì dán key vào URL. Hướng dẫn từng bước có trong bài Lỗi 401 Unauthorized.
Lỗi 404: sai endpoint hoặc tham số
Gõ sai tên thành phố (q=hanio) hoặc dùng endpoint cũ, node báo “The resource you are requesting could not be found” kèm mã 404. Kiểm lại đường dẫn /data/2.5/weather và tham số trong tài liệu API; tên thành phố có thể thêm mã quốc gia như q=hanoi,vn.
Lỗi 429: gọi API quá nhanh
Workflow chạy dày hoặc xử lý nhiều item cùng lúc dễ vượt giới hạn của gói API, node báo “The service is receiving too many requests from you”. Mở Options > Batching, đặt Items per Batch và Batch Interval (ms); ví dụ 1 item mỗi 1.000 ms là một request mỗi giây. Với lịch chạy, dùng Schedule Trigger ở chu kỳ phù hợp với hạn mức thay vì chạy liên tục.
Lỗi 500: máy chủ API gặp sự cố
Mã 500 kèm thông báo “The service was not able to process your request” nghĩa là lỗi nằm ở dịch vụ, không phải cấu hình workflow. Bật Retry On Fail để node tự thử lại, kiểm trang trạng thái của nhà cung cấp, và ghi lại thời điểm lỗi nếu cần báo hỗ trợ.
Lỗi SSL: chứng chỉ của API không hợp lệ
Lỗi SSL xảy ra khi n8n không xác minh được chứng chỉ của máy chủ API: chứng chỉ hết hạn, sai tên miền, thiếu chứng chỉ trung gian, hoặc proxy công ty chèn chứng chỉ riêng.
Kiểm chứng chỉ của API bằng trình duyệt hoặc công cụ như SSL Labs; tìm hiểu thêm về chứng chỉ SSL. Tùy chọn Options > Ignore SSL Issues trong node HTTP Request chỉ nên bật tạm để chẩn đoán, vì nó tắt lớp bảo vệ chống giả mạo máy chủ.
Cách xem chi tiết lỗi API trong n8n
n8n hiển thị chi tiết lỗi ở panel OUTPUT của node lỗi, gồm Error code, Full message và request đã gửi. Với workflow đã Publish, lỗi nằm trong tab Executions thay vì trên canvas. Khi thông báo chưa đủ để đoán nguyên nhân, bật thêm tùy chọn trả về header hoặc chạy lại đúng dữ liệu cũ:
- Panel OUTPUT: mở node lỗi, xem Error details. Phần Request cho biết URL, header, tham số n8n đã gửi (thông tin nhạy cảm được ẩn).
- Include Response Headers and Status: trong Options > Response, bật để nhận cả mã trạng thái và header, hữu ích khi API báo hạn mức trong header.
- Never Error: cũng trong Options > Response, node trả kết quả kể cả khi mã khác 2xx, để node phía sau tự rẽ nhánh theo mã.
- Tab Executions: workflow đã Publish không hiện dữ liệu trên canvas; mở Executions để xem lần chạy lỗi. Xem thêm cách đọc execution log trong n8n.
- Debug in editor: từ một execution cũ, sao chép dữ liệu vào editor để chạy lại đúng dữ liệu đã gây lỗi.
Cách tự xử lý lỗi API trong workflow
Workflow chạy tự động cần có sẵn cách phản ứng khi API lỗi, vì không ai ngồi xem canvas lúc 3 giờ sáng. n8n có ba lớp xử lý: thử lại tại node, rẽ nhánh khi lỗi và workflow báo động riêng, theo tài liệu node HTTP Request và hướng dẫn xử lý lỗi:
- Retry On Fail (tab Settings của node): đặt Max Tries và Wait Between Tries (ms). Dùng cho 429, 5xx, timeout thoáng qua; không dùng cho 401, 403, 404.
- On Error = Continue (using error output): node có thêm đầu ra lỗi để ghi log, gửi thông báo hoặc trả dữ liệu dự phòng, các item khác vẫn đi tiếp.
- Error workflow: tạo workflow bắt đầu bằng Error Trigger (gửi Telegram, email), rồi chọn nó ở Settings > Error workflow của workflow chính. Node Stop and Error dùng để chủ động đánh dấu một tình huống là lỗi.
Node HTTP Request có bị lỗi CORS không?
Không. CORS là cơ chế của trình duyệt, kiểm soát việc một trang web gọi tới tên miền khác. Node HTTP Request chạy trên máy chủ n8n, không chạy trong trình duyệt, nên không bị CORS chặn. Thêm header Access-Control-Allow-Origin vào request từ n8n cũng không có tác dụng, vì header này do máy chủ trả về.
CORS chỉ liên quan khi chiều ngược lại: một trang web gọi webhook của n8n từ trình duyệt và bị chặn. Khi đó đặt tùy chọn Allowed Origins (CORS) trong node Webhook. Chi tiết có trong bài node Webhook trong n8n.
Đọc tiếp theo từng lỗi
Các bài lỗi n8n trên blog Tino chia theo nhóm: lỗi xác thực, lỗi của dịch vụ Google, lỗi quá thời gian chờ và lỗi hiệu năng. Bảng mã lỗi ở trên đã dẫn tới từng bài; danh sách đầy đủ như sau, mỗi bài kèm ví dụ dựng lại trên n8n:
- Lỗi 401 Unauthorized: định nghĩa, phân biệt 401 với 403, cách sửa trên website, API và trong n8n.
- Sửa lỗi tích hợp Google Sheets, Google Drive với n8n: lỗi 403, 404, 429 và token hết hạn của Google.
- Timeout trong n8n: lỗi quá thời gian chờ ở node HTTP Request, webhook và giới hạn thời gian chạy workflow.
- Tại sao workflow trong n8n chạy chậm: dữ liệu lớn, database phình, cấu hình máy chủ.
Nếu bạn đang dựng workflow đầu tiên, bắt đầu từ cách tạo workflow trên n8n và cách thêm API vào n8n; phần credential có ở bài credential trong n8n.
Những câu hỏi thường gặp
Vì sao API trả về HTML thay vì JSON?
Thường do request đi nhầm chỗ: sai URL nên nhận trang lỗi của máy chủ web, bị chuyển hướng sang trang đăng nhập, hoặc gặp trang chặn của tường lửa. Bật Include Response Headers and Status để xem mã trạng thái và header Content-Type, rồi kiểm lại URL và xác thực.
Lỗi API do n8n hay do dịch vụ bên kia?
Nhìn mã trạng thái: 4xx thường do request từ n8n (tham số, xác thực, tốc độ gửi), 5xx do dịch vụ bên kia. Gọi thử cùng request bằng curl hoặc Postman; nếu curl cũng lỗi thì vấn đề không nằm ở cấu hình node.
n8n Cloud và n8n tự host có gặp lỗi API khác nhau không?
Mã lỗi giống nhau. Khác biệt nằm ở mạng: bản tự host trong Docker hay gặp ECONNREFUSED khi gọi localhost, còn n8n Cloud không gọi được dịch vụ chỉ chạy trong mạng nội bộ của bạn nếu không mở qua tunnel.
Nên làm gì khi đã thử hết mà lỗi API vẫn còn?
Ghi lại mã lỗi, Full message, thời điểm và request (đã che key), rồi gửi cho bộ phận hỗ trợ của nhà cung cấp API. Diễn đàn community.n8n.io hữu ích khi lỗi nằm ở cách cấu hình node.
Muốn chạy n8n 24/7 mà không tự cài? VPS n8n của Tino cài sẵn n8n trên VPS NVMe đặt tại Việt Nam; bạn vẫn có quyền root để cấu hình. Xem cấu hình và giá trên trang sản phẩm.
