Buổi sáng, workflow đồng bộ danh sách khách hàng chạy bình thường. Đến lúc cả team cùng bật lịch cập nhật, API instance n8n bắt đầu trả 429. Làm sao giới hạn lưu lượng mà không khiến một workflow ngốn hết lượt của các nhóm khác?
n8n public API rate limits giải quyết đúng bài toán này: đặt hạn mức theo API key khi ứng dụng hoặc workflow gọi /api/v1 trên chính instance n8n. Tính năng có từ n8n 2.47.0, mặc định tắt. Bài này hướng dẫn kiểm tra phiên bản, bật giới hạn cho self-host, đọc tín hiệu phản hồi và thiết kế retry không làm lặp thao tác. Đây không phải giới hạn do API của đối tác áp lên HTTP Request node. [1][2]

Tóm tắt nhanh
- n8n 2.47.0+ hỗ trợ rate limits cho public API; chủ instance hoặc admin phải bật.
- Giới hạn theo API key, chia đọc/ghi và toàn bộ endpoint/từng endpoint.
- 429 có
Retry-After; chờ đúng thời gian rồi thêm jitter, không retry liên tục. - Batching giảm burst;
Idempotency-Keygiữ an toàn cho POST được hỗ trợ khi phải thử lại.
n8n public API rate limits áp dụng ở đâu?
Giới hạn chỉ đếm yêu cầu có API key tới /api/v1 của instance n8n, theo từng key riêng. Hai key thuộc cùng một tài khoản vẫn có hai bộ đếm. Giao diện editor không tính vào hạn mức này. Do đó, bật giới hạn không đồng nghĩa mọi trang trong n8n đều bị chặn; đồng thời cũng không giới hạn API mà workflow gọi tới CRM hay cổng thanh toán bên ngoài. [2]
Ví dụ hệ thống Việt Nam có một job đồng bộ đơn hàng và một job cập nhật báo cáo. Nếu mỗi job có key riêng, job đồng bộ gửi quá nhiều request sẽ chạm giới hạn của key nó, còn job báo cáo có ngân sách request độc lập. Nếu cả hai dùng chung key, chúng chia sẻ hạn mức: một job gọi dồn dập có thể khiến job kia gặp 429. Đây là lý do tách key theo ứng dụng hoặc luồng vận hành, chứ không phải cấp một key chung cho cả công ty.
Điểm cần nhớ: quota theo key không thay cho việc đo tải CPU, database hoặc worker. Cần theo dõi cả thời gian đáp ứng, backlog và số lần 429 để biết bottleneck thật. Với website có workflow tự động, bạn có thể đối chiếu thêm hướng dẫn quản trị và quản lý website: điều phối tải là công việc vận hành, không chỉ cài thêm tính năng.

Mặc định có những ngưỡng nào?
Khi bật tính năng, n8n dùng bốn mức mặc định cho yêu cầu đọc và ghi, theo toàn bộ API và theo từng endpoint. Một request được xét đồng thời ở hai tầng: hạn mức tất cả endpoint của key và hạn mức endpoint cụ thể. Nếu vượt một trong hai, request bị từ chối. GET là đọc; POST, PUT, PATCH, DELETE là ghi. Cửa sổ mặc định của cả bốn mức là 60 giây. [2]
| Loại request | Tất cả endpoint | Mỗi endpoint | Cửa sổ mặc định |
|---|---|---|---|
| Đọc (GET) | 1.200 | 1.000 | 60 giây |
| Ghi (POST/PUT/PATCH/DELETE) | 600 | 500 | 60 giây |
Đây là cấu hình mặc định khi giới hạn được bật, không phải cam kết rằng một instance luôn xử lý được từng ấy request. Một request nặng có thể làm hệ thống chậm trước khi chạm trần; ngược lại, một job nhẹ vẫn gặp 429 nếu gửi thành burst. Team nên đo lưu lượng thực trước, rồi đặt ngưỡng thấp hơn nếu cần bảo vệ hệ thống trong giờ cao điểm.
Endpoint được tính bằng phương thức và đường dẫn dạng endpoint, không phải mỗi ID đối tượng là một bucket riêng: ví dụ các workflow ID khác nhau trong GET /api/v1/workflows/{workflowId} vẫn thuộc cùng một loại endpoint. Điều này quan trọng nếu một job đang duyệt hàng trăm workflow: đổi ID trong URL không làm mất giới hạn per-endpoint. [2]

Bật n8n public API rate limits trên self-host ra sao?
Trước tiên xác nhận instance chạy n8n 2.47.0 trở lên; sau đó chủ instance hoặc admin bật trong Settings > Policies, hoặc bật bằng biến môi trường và khởi động lại instance. Trên giao diện, mở Public API Limits, bật Enable API key rate limits, điều chỉnh giới hạn và cửa sổ rồi lưu. n8n yêu cầu ít nhất một hạn mức có giá trị khi bật. [2]
Với self-host dùng cấu hình triển khai, bạn có thể đặt biến môi trường sau ở nơi quản lý deployment, không dán vào file công khai. Nếu dùng Docker Compose, thêm vào cấu hình môi trường được kiểm soát và restart dịch vụ n8n theo quy trình vận hành của bạn; kiểm tra backup và thời gian gián đoạn trước khi đổi trên production.
# Ví dụ giá trị cấu hình, không phải lệnh chạy trên server sản xuất N8N_PUBLIC_API_RATE_LIMIT_ENABLED=true N8N_PUBLIC_API_RATE_LIMIT_GLOBAL_READ_LIMIT=1200 N8N_PUBLIC_API_RATE_LIMIT_GLOBAL_WRITE_LIMIT=600
Hai biến hạn mức ở ví dụ lặp lại mặc định để minh họa tên cấu hình; không cần đặt nếu giữ nguyên giá trị mặc định. Docs còn có biến riêng cho từng endpoint và độ dài cửa sổ. Nếu bạn quản lý config bằng environment, các trường bị environment quản lý không thể đổi thành giá trị khác qua API settings; lên kế hoạch dùng một nguồn cấu hình nhất quán. [2][4]
Muốn xem cấu hình theo API, admin với scope securitySettings:manage có thể dùng GET /api/v1/settings/rate-limits. PUT thay thế cấu hình toàn bộ, không phải cập nhật một trường lẻ; đừng gửi một object thiếu field từ script ad-hoc. Ví dụ thao tác thật cần dùng API key có quyền quản lý, nên mình không đề xuất gọi thử PUT trên instance đang vận hành. Hãy đọc cấu hình hiện tại, lưu snapshot an toàn và review diff trước khi thay đổi. [4]
Thú vị nhỉ: mặc định “off” là lý do bạn có thể đang không thấy header rate limit dù instance đã nâng phiên bản. Đừng vội kết luận feature không tồn tại. Kiểm tra phiên bản, trạng thái bật và loại request trước khi điều tra load balancer.

Khi nhận 429, đọc header và chờ thế nào?
429 nghĩa là request vượt hạn mức và n8n không chạy request đó. Đọc Retry-After để biết cần chờ bao nhiêu giây trước khi thử lại. Không retry ngay lập tức: request gửi quá sớm lại nhận 429. Nếu hai tầng giới hạn cùng bị vượt, thời gian chờ phản ánh tầng cần chờ lâu hơn. Request bị từ chối không làm tăng bộ đếm. [2]
Trên phản hồi thành công khi giới hạn bật và request dùng API key, X-RateLimit-Limit cho biết ngưỡng, X-RateLimit-Remaining là số lượt còn lại, X-RateLimit-Reset là thời điểm kết thúc cửa sổ theo Unix timestamp (giây). Các header này cho thấy giới hạn nào đang còn ít lượt nhất. Nếu header không xuất hiện, kiểm tra feature đang tắt hoặc request không dùng API key trước khi viết thêm mã xử lý. [2]
- Ghi log status, endpoint, key identifier an toàn (không log API key thô),
Retry-Aftervà remaining. - Chờ ít nhất số giây trong
Retry-After; cộng thêm jitter ngẫu nhiên tối đa 5 giây để nhiều worker không cùng thức dậy. - Giảm tốc request gửi tiếp theo dựa trên
X-RateLimit-Remainingvà thời điểm reset; tránh một burst mới sau mỗi lần retry. - Đặt số lần thử tối đa và đưa job còn lỗi vào hàng đợi theo dõi; không tạo vòng lặp vô hạn.
Ví dụ client nhận Retry-After: 12: chờ tối thiểu 12 giây, cộng độ trễ ngẫu nhiên nhỏ, rồi mới thử lại. Con số 12 chỉ để minh họa, không phải mức chờ mặc định của n8n. Với nhiều worker, nên tập trung quản lý nhịp gửi ở hàng đợi thay vì để mỗi worker tự retry độc lập.

Workflow n8n nên chia batch thế nào để tránh 429?
Khi n8n node hoặc HTTP Request node gọi lại public API của chính instance, dùng Batching trong Request Options để giảm tốc số item được xử lý. Mỗi item có thể tạo một request. Một workflow với 1.000 item có thể gửi rất nhiều request gần cùng lúc; nút Retry On Fail không giải quyết triệt để vì khoảng chờ tối đa của nút chỉ 5 giây, thường ngắn hơn thời gian trong Retry-After. [2][5]
Ví dụ giả định: một luồng gửi 5 item mỗi giây, tương đương 300 request/phút nếu mỗi item tạo một request. Mức này thấp hơn bốn ngưỡng mặc định, nhưng không bảo đảm an toàn nếu nhiều client cùng dùng key hoặc endpoint có ngưỡng đã chỉnh thấp hơn. Chọn Items per Batch và Batch Interval (ms) dựa trên hạn mức thật và số luồng dùng chung key; giảm burst trong giờ cao điểm, không chỉ giảm tổng request theo ngày.
Thử trên staging bằng một lượng item nhỏ, quan sát X-RateLimit-Remaining và độ trễ xử lý, rồi tăng dần. Nếu job phải xử lý toàn bộ dữ liệu trước hạn, chia thành nhiều đợt với checkpoint để có thể tiếp tục sau khi bị ngắt. Cùng tinh thần đó, lịch chạy nền dồn vào một thời điểm dễ làm website chậm: phân bổ tải quan trọng hơn tăng cấu hình máy ngay lập tức.
Giới hạn public API không áp dụng cho các API ngoài như CRM hay cổng vận chuyển mà workflow gọi. Nếu phản hồi 429 đến từ dịch vụ đối tác, bạn phải đọc chính sách rate limit của họ, không chỉnh biến N8N_PUBLIC_API_RATE_LIMIT_* với hy vọng sửa được. Phân biệt nguồn phản hồi qua hostname, đường dẫn request và log là bước chẩn đoán đầu tiên.
Retry POST mà không tạo bản ghi trùng bằng cách nào?
Với endpoint POST public API n8n có hỗ trợ, gửi cùng Idempotency-Key cho lần gọi đầu và mọi lần retry của cùng một thao tác. Tính năng idempotency có từ n8n 2.45.0, giữ kết quả thành công đầu tiên trong 12 giờ. Key mới dành cho thao tác mới; không tái sử dụng một key cho nhiều payload khác nhau. Không phải mọi phương thức hay endpoint đều xử lý key này: kiểm tra API reference trước khi triển khai. [3]
Giả sử client gửi yêu cầu tạo workflow nhưng mạng đứt trước khi nhận response: bạn không biết server đã tạo xong hay chưa. Retry POST không có idempotency key có thể tạo thêm bản sao. Với một key ổn định cho chính thao tác đó, n8n có thể trả về kết quả thành công trước thay vì thực hiện lại trong thời gian hỗ trợ. Đây là lớp bảo vệ cho lỗi không rõ kết quả, khác với 429 vốn là request bị từ chối trước khi chạy.
Key cần dài 1-128 ký tự ASCII hiển thị và không chứa khoảng trắng bên trong; UUID v4 là lựa chọn phù hợp. Lưu key cùng job trong hệ thống điều phối, không tạo key mới ở mỗi lần thử. Không đưa API key xác thực vào bài viết, log hay URL. Nếu đã quá cửa sổ 12 giờ, kiểm tra trạng thái đối tượng trước khi thử lại thay vì giả định yêu cầu vẫn được deduplicate. [3]
Mình khuyên bắt đầu bằng một key riêng cho mỗi luồng, bật giới hạn trên staging, quan sát header vài ngày vận hành, rồi mới chốt ngưỡng production. Nếu bạn có workflow đang gặp 429, hãy xem lại nguồn phát sinh request trước: từ public API của n8n hay từ nhà cung cấp khác? Chỉ sau đó mới chọn đúng biện pháp.
Nguồn tham khảo
- [1] n8n Blog — Public API rate limits, 13/11/2026
- [2] n8n Docs — Rate limits (kiểm tra 20/11/2026)
- [3] n8n Docs — API idempotency
- [4] n8n Docs — Settings rate limits endpoint
- [5] n8n Docs — n8n node batching
- [6] n8n Blog — API rate limiting patterns
Các câu hỏi thường gặp
n8n public API rate limits có bật sẵn không?
Không. Từ n8n 2.47.0, admin hoặc chủ instance có thể bật trong Settings > Policies; self-host cũng có thể bật qua biến môi trường và restart.
Hai workflow dùng chung API key có chia sẻ hạn mức không?
Có. n8n đếm theo API key, nên các client dùng chung key chia sẻ bộ đếm; key khác nhau có bộ đếm riêng ngay cả khi thuộc cùng người dùng.
Nhận 429 thì có nên bật Retry On Fail không?
Không nên xem đây là giải pháp duy nhất. Khoảng chờ của nút tối đa 5 giây có thể ngắn hơn Retry-After; hãy giảm tốc bằng batching và thiết kế hàng đợi chờ đúng thời gian server yêu cầu.
Giới hạn này có chặn API của dịch vụ bên thứ ba không?
Không. Nó áp dụng cho request có API key đến /api/v1 của chính instance n8n. Nếu CRM trả 429, cần xử lý theo chính sách và header của CRM.
Idempotency-Key có thay thế được rate limit không?
Không. Rate limit kiểm soát nhịp request; Idempotency-Key ngăn thực hiện lặp lại một POST được hỗ trợ khi client không chắc lần trước đã thành công hay chưa.
Có thể sửa một trường settings bằng PUT mà bỏ các trường còn lại không?
Không nên. PUT /api/v1/settings/rate-limits thay thế toàn bộ cấu hình; hãy lấy cấu hình hiện tại, cập nhật có kiểm soát và gửi đủ field. Trường do environment quản lý không được đổi qua API.
