Giới hạn tốc độ API

Đây là các rate limit API (giới hạn tốc độ) của một hệ thống ReputeCast: mỗi bên gọi được thực hiện bao nhiêu yêu cầu, máy chủ đếm chúng thế nào, và máy chủ trả về gì khi một bên gọi vượt giới hạn.

Giới hạn

Thiết lập	Mặc định	Cách thay đổi
Endpoint đăng nhập (/api/v1/auth/*)	30 requests per minute per IP address	Cấu hình http.rate_limit_auth
REST API	600 requests per minute per API key or agent token (per IP address for browser sessions)	Cấu hình http.rate_limit_api; 0 tắt giới hạn này và cả giới hạn đăng nhập
Endpoint gửi và gửi theo lô của Giao dịch	50 messages per second per send-only key	Trường API transactional.ratePerSecond trên khóa, 1–10,000
Máy chủ MCP (/mcp)	120 calls per minute per agent	Cài đặt › Khóa và MCP › Đổi giới hạn, 1–6,000
API chuyển đổi	600 per minute per API key	Cố định
Cách đếm giới hạn	Sliding 1-minute window per server process; IPv6 addresses grouped by /64	Cố định; hãy đặt http.trusted_proxies để các client sau proxy của bạn không dùng chung một địa chỉ
Phản hồi khi chạm giới hạn	HTTP 429 with Retry-After and X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset headers	Cố định

• Lệnh gọi bằng khóa API được đếm theo từng khóa, bất kể đến từ địa chỉ nào. Lệnh gọi không có bearer token (phiên trình duyệt) được đếm theo địa chỉ IP của client.
• Lệnh gọi gửi giao dịch đơn lẻ và theo lô không tính vào giới hạn yêu cầu của mỗi khóa; thay vào đó, mỗi khóa có tốc độ gửi thư riêng (xem gửi email giao dịch bằng API).
• Trang công khai, liên kết theo dõi và webhook của nhà cung cấp (/p/, /t/, /hooks/) nằm ngoài các giới hạn này. Biểu mẫu đăng ký có giới hạn riêng (xem biểu mẫu đăng ký).
• Mỗi tiến trình máy chủ đếm riêng. Khi có nhiều node web phía sau một bộ cân bằng tải, một bên gọi có thể chạm giới hạn trên từng node.

Header

Header	Được gửi kèm	Giá trị
X-RateLimit-Limit	Mọi phản hồi /api/ trừ gửi giao dịch đơn lẻ và theo lô	Số yêu cầu được phép mỗi phút cho bên gọi này.
X-RateLimit-Remaining	Như trên	Số yêu cầu còn lại trong khung thời gian hiện tại.
X-RateLimit-Reset	Như trên	Thời điểm khung thời gian hiện tại kết thúc, tính bằng giây Unix.
Retry-After	Phản hồi 429	Số giây cần chờ. 60 với giới hạn theo khóa, giới hạn đăng nhập và giới hạn MCP; với gửi giao dịch và chuyển đổi, là thời gian cho đến khi khóa có chỗ trở lại (tối thiểu 1).

Header phản hồi

HTTP/1.1 200 OK
Content-Type: application/json
X-Ratelimit-Limit: 600
X-Ratelimit-Remaining: 590
X-Ratelimit-Reset: 1792671646

Tên header HTTP không phân biệt chữ hoa chữ thường; hãy đọc chúng mà không phụ thuộc vào kiểu chữ.

Phản hồi khi chạm giới hạn

Khi vượt giới hạn yêu cầu của mỗi khóa:

429 Too Many Requests

{
  "code": "rate_limited",
  "detail": "Rate limit reached. Requests resume within a minute; batch endpoints accept up to 1,000 items per call.",
  "status": 429,
  "title": "Too Many Requests"
}

Con số “1,000 items” trong thông báo này đúng với thao tác thêm vào danh sách chặn gửi; thao tác gửi giao dịch theo lô nhận tối đa 100 thư.

Khi vượt tốc độ gửi thư của một khóa chỉ gửi (ở đây là 50 thư mỗi giây), kèm Retry-After: 1:

429 Too Many Requests

{
  "title": "Too Many Requests",
  "status": 429,
  "detail": "This key sends at most 50 messages per second. Wait 1 second (Retry-After) and send again with the same idempotency key.",
  "code": "rate_limited"
}

Khi vượt giới hạn đăng nhập, detail là “Mạng của bạn đã thử đăng nhập quá nhiều lần. Hãy đợi một phút rồi thử lại.” Ứng dụng web gửi ngôn ngữ của nó trong Accept-Language; khi không có header này, detail là “Too many sign-in attempts from your network. Wait a minute and try again.” Máy chủ MCP báo giới hạn của nó bằng văn bản thuần kèm Retry-After: 60: “Rate limit reached: 120 calls per minute per agent. Calls resume within a minute.” (với giới hạn riêng của tác tử thay cho 120). Xem lỗi API để biết định dạng problem document.

Giữ dưới giới hạn

• Đọc X-RateLimit-Remaining và giảm tốc trước khi giá trị này về 0.
• Khi nhận 429, hãy chờ số giây trong Retry-After rồi thử lại. Thử lại sớm hơn chỉ nhận thêm một 429.
• Dùng thao tác theo lô và kích thước trang lớn nhất bạn cần (xem phân trang).
• Nhận webhook thay vì hỏi định kỳ để biết thay đổi.
• Thử lại lượt gửi giao dịch với cùng Idempotency-Key, để mỗi thư chỉ được gửi một lần.
• Cấp cho mỗi tác vụ một khóa riêng, để một tác vụ bận rộn không dùng hết giới hạn của tác vụ khác.

Thay đổi giới hạn

Người vận hành máy chủ đặt giới hạn yêu cầu trong cấu hình: http.rate_limit_api cho lệnh gọi API và http.rate_limit_auth cho đăng nhập (xem tham chiếu cấu hình). Đặt http.rate_limit_api thành 0 sẽ tắt cả hai. Khi ReputeCast chạy sau một reverse proxy, hãy đặt http.trusted_proxies để các bên gọi không có khóa được đếm theo địa chỉ của chính họ, không phải địa chỉ của proxy (xem reverse proxy và TLS). Tốc độ gửi thư của khóa chỉ gửi được đặt khi tạo khóa, còn giới hạn lệnh gọi của tác tử MCP được đặt trong phần cài đặt MCP của không gian làm việc.