Giới Hạn Tốc Độ

Cách giới hạn hoạt động

TokSpan giới hạn khối lượng yêu cầu và hạn mức tài khoản để không khách hàng nào có thể làm nghẽn hạ tầng dùng chung. Ba loại giới hạn được áp dụng:

• Giới hạn tốc độ theo tài khoản — Số yêu cầu tối đa tài khoản của bạn có thể thực hiện trong một khoảng thời gian (request/phút và token/phút, có thể cấu hình theo gói/nhóm).
• Giới hạn của nhà cung cấp ngược dòng — Mỗi nhà cung cấp mô hình áp dụng trần thông lượng riêng. Nếu nhà cung cấp bị bão hòa, yêu cầu có thể bị xếp hàng hoặc trả về 429.
• Số dư / hạn mức tài khoản — Mỗi yêu cầu tiêu thụ một phần nhỏ số dư của bạn khi sử dụng token. Khi số dư về 0, yêu cầu bị từ chối.

Xử lý phản hồi 429

Phản hồi 429 Too Many Requests nghĩa là bạn đã chạm giới hạn tốc độ hoặc cạn hạn mức. Phản hồi có thể kèm header Retry-After cho biết số giây cần chờ. Cách xử lý được khuyến nghị:

1. Kiểm tra header Retry-After nếu có, và chờ đúng thời gian đó trước khi thử lại.
2. Ngược lại, thử lại với exponential backoff và jitter (ví dụ: 1s → 2s → 4s, kèm độ lệch ngẫu nhiên nhỏ) để các lần thử lại không dồn vào một thời điểm.
3. Nếu bạn liên tục chạm giới hạn trong production, hãy liên hệ chúng tôi để nâng giới hạn tốc độ của tài khoản.

Số dư / hạn mức không đủ

Khi số dư của tài khoản hoặc khóa API cạn kiệt, yêu cầu bị từ chối. Phản hồi lỗi dùng kiểu new_api_error với thông báo nhắc đến hạn mức hoặc số dư (ví dụ: insufficient_user_quota). Đây không phải giới hạn tốc độ — thử lại sẽ không giúp ích cho đến khi bạn nạp credit.

Yêu cầu nâng giới hạn

Cần giới hạn tốc độ cao hơn cho khối lượng production? Liên hệ hỗ trợ với email tài khoản và khối lượng yêu cầu dự kiến, chúng tôi sẽ điều chỉnh giới hạn hoặc thiết lập gói enterprise cho bạn.