Giới hạn
Rate limit, số run hoạt động tối đa mỗi end-user, ngân sách token mỗi ngày.
Bốn loại giới hạn khác nhau áp dụng lên bề mặt public. Tất cả đều trả về
lỗi 429 với code: "rate_limited" hoặc code: "budget_exceeded" — xem
Lỗi để biết hình lỗi đầy đủ.
Đổi token (POST /v2/token)
Tính theo (publishable key, IP gọi), mặc định 60 lần/phút. Chỉ áp
dụng cho đổi token bằng pk (ẩn danh hoặc có ký) — đổi bằng API key
(server-to-server) không bị giới hạn ở endpoint này. Vượt quá trả
rate_limited với scope: "token_exchange" và retry_after (giây).
Gửi message của một end-user
Tính theo end-user (không phải theo IP), mặc định 20 tin nhắn/phút —
tổ chức bạn có thể chỉnh trong giới hạn operator cho phép. Áp dụng cho
message gửi qua widget hoặc qua
POST /v2/conversations/{id}/messages.
scope: "end_user".
Gửi message của một API key
Tính theo API key, mặc định 300 lần/phút — cũng chỉnh được trong giới
hạn operator. Áp dụng cho POST /v2/chat.
scope: "api_key".
Số run đang hoạt động cùng lúc
Mỗi end-user (kể cả end-user service đại diện cho một API key không khai
end_user_id) tối đa 3 run đang chạy cùng lúc. Gửi message thứ tư
trong lúc ba run trước còn đang chạy trả về rate_limited với
scope: "active_runs" — đợi một run kết thúc (hoặc huỷ
một run) rồi gửi lại. Một run đang chờ người dùng xác nhận một hành động hoặc trả lời câu hỏi
vẫn đếm là đang hoạt động.
Đồng thời và hàng đợi (theo tổ chức)
Tổ chức bạn chạy được một số run chat cùng lúc (mặc định 10) và giữ một số run chờ slot trống (mặc định 50). Cả hai do đội Harnix đặt cho tổ chức của bạn; bạn xem chúng ở Console → Hạn mức & giới hạn. Khi một message mới chỉ có thể vào một hàng đợi đã đầy, nó bị từ chối ngay thay vì chờ vô hạn:
429 queue_fullvớiscope: "org",retry_after(giây) và headerRetry-After— không tạo message, không tạo run. Đợiretry_aftergiây rồi gửi lại.scope: "deployment"nghĩa là toàn nền tảng đang quá tải và tổ chức bạn không còn slot trống; xử lý y như trên.- Gửi lại với cùng
Idempotency-Keynhận lại run cũ, không bao giờ bịqueue_full.
Việc xử lý tài liệu chạy nền và không bao giờ tính vào các giới hạn này.
Ngân sách token mỗi ngày
Tổ chức bạn có thể đặt một ngân sách token (tổng số token model tiêu thụ) theo ngày — cho toàn tổ chức, và/hoặc riêng cho từng agent (Console → Hạn mức & giới hạn). Hết ngân sách:
- Một request tạo run mới trả
429 budget_exceededvớiscope: "org"hoặc"agent"ngay lập tức, không tạo run. - Một run đang chạy mà tổ chức/agent hết ngân sách giữa chừng (một run
khác vừa tiêu hết) sẽ dừng ở checkpoint an toàn tiếp theo, cũng với
errorbắt đầu bằngbudget_exceeded.
Không có ngân sách nào đặt = không giới hạn. Ngày tính theo giờ UTC.
Cửa sổ xác nhận hành động (không phải một rate limit)
Khi agent muốn gọi một tool của connector cần xác nhận, run dừng và chờ
người dùng trả lời tối đa 5 phút (mặc định của Harnix, chung cho mọi tổ
chức; expires_at trên khung approval cho biết mốc chính xác). Quá hạn,
hành động tính như bị từ chối: tool không chạy, trợ lý nói với người dùng
rằng hành động không được thực hiện, và run kết thúc bình thường — không có
lỗi 429 nào. Xem Idempotency & huỷ
và Connector.
Cửa sổ chờ trả lời câu hỏi (không phải một rate limit)
Khi agent gọi tool ask_user, run dừng và chờ câu trả lời tối đa 10 phút
(mặc định của Harnix, chung cho mọi tổ chức, cấu hình deployment
ASK_USER_TIMEOUT_SECONDS; expires_at trên khung question cho biết mốc
chính xác). Quá hạn, model nhận thông báo câu hỏi đã hết hạn và tiếp tục câu
trả lời với những thông tin hiện có — run kết thúc bình thường (succeeded),
không có lỗi 429 nào. Xem Idempotency & huỷ
và Tool.
Lưu trữ trace (không phải một rate limit)
Tổ chức bạn có một cấu hình riêng về số ngày giữ nội dung trace (Console →
Hạn mức & giới hạn) — không liên quan tới bốn
loại giới hạn ở trên, không trả lỗi 429, và không ảnh hưởng tới hội thoại
hay message bạn đọc qua API. Xem Lượt chạy & Trace.
Bước tiếp theo
- Lỗi — hình lỗi
{code, message, scope?, retry_after?}. - Checklist trước khi lên production —
xử lý
429đúng cách trước khi phát hành.