Rate Limit

Mỗi request API của FourA đều đi qua hệ thống giới hạn rate limit. Bạn sẽ gặp hai loại giới hạn: concurrency (yêu cầu đồng thời) và RPM (số request mỗi phút). Cả hai đều được áp dụng cho từng dịch vụ.

Cách Hoạt động của Rate Limit

API áp dụng các giới hạn ở hai cấp độ:

1. Giới hạn API toàn cục: áp dụng cho tất cả các request bất kể endpoint nào. Bước kiểm tra này được thực hiện đầu tiên.
2. Giới hạn theo từng dịch vụ: áp dụng riêng biệt cho từng endpoint (single, proxy, browser). Bước kiểm tra này chỉ chạy nếu giới hạn toàn cục được thông qua.

Nếu giới hạn toàn cục bị vượt quá, bước kiểm tra theo từng dịch vụ sẽ không chạy. Một request phải vượt qua cả hai bước kiểm tra trước khi đến được backend.

Mỗi cấp độ theo dõi hai chỉ số:

• Concurrency: số lượng request đang chạy cùng một lúc.
• RPM: số lượng request bạn đã gửi trong 60 giây qua.

Phản hồi khi Gặp Rate Limit

Khi bạn vượt quá giới hạn, API sẽ trả về một phản hồi JSON chứa thông tin sử dụng hiện tại và các giới hạn đang áp dụng.

429: Vượt quá RPM

{
  "error": "Rate limit exceeded",
  "status": 429,
  "service": "single",
  "retryAfter": 5,
  "current": {
    "concurrency": 12,
    "rpm": 3000
  },
  "limits": {
    "maxConcurrency": 500,
    "maxRpm": 3000
  }
}

Bạn đã gửi quá nhiều request trong phút vừa qua. Hãy đợi hết khoảng thời gian retryAfter trước khi gửi thêm.

503: Vượt quá Concurrency

{
  "error": "Service at capacity",
  "status": 503,
  "service": "proxy",
  "retryAfter": 2,
  "current": {
    "concurrency": 500,
    "rpm": 1200
  },
  "limits": {
    "maxConcurrency": 500,
    "maxRpm": 3000
  }
}

Có quá nhiều request đang chạy cùng một lúc. Một số request trước đó của bạn vẫn chưa hoàn thành.

Dịch vụ bị Vô hiệu hóa

Khi một dịch vụ tạm thời bị ngắt kết nối để bảo trì, API sẽ trả về mã 503 với một thông báo lỗi khác:

{
  "error": "Service disabled",
  "status": 503,
  "retryAfter": 60
}

Đây không phải là lỗi rate limit. Dịch vụ hiện tạm thời không khả dụng. Hãy kiểm tra giá trị retryAfter và thử lại sau số giây đó. Lỗi này thường sẽ được khắc phục trong vòng vài phút.

Đừng nhầm lẫn lỗi này với lỗi 503 do concurrency. Phản hồi "Service disabled" sẽ không bao gồm các trường current hoặc limits.

Các Trường Phản hồi

Xử lý Rate Limit

Sử dụng trường retryAfter để triển khai cơ chế backoff:

import requests
import time

def fetch(url, max_retries=5):
    for attempt in range(max_retries):
        resp = requests.post(
            "https://eu.api.foura.ai/api/single/",
            headers={
                "X-API-Key": "YOUR_API_KEY",
                "Content-Type": "application/json"
            },
            json={"method": "GET", "url": url}
        )

        if resp.status_code in (429, 503):
            data = resp.json()
            wait = data.get("retryAfter", 5)
            time.sleep(wait)
            continue

        return resp

    raise Exception("Max retries exceeded")

Mẹo

• Kiểm tra các trường current trong phản hồi rate limit để hiểu rõ mô hình sử dụng của bạn.
• Nếu bạn liên tục gặp giới hạn concurrency, hãy giảm số lượng request song song.
• Nếu bạn gặp giới hạn RPM, hãy thêm một khoảng trễ nhỏ giữa các request hoặc gom chúng thành nhóm (batch) trong một khoảng thời gian dài hơn.
• Giá trị retryAfter thay đổi tùy theo loại giới hạn: 2 giây đối với concurrency, 5 giây đối với RPM.
• Phản hồi "Service disabled" có nghĩa là hệ thống đang được bảo trì. Đừng tiếp tục gửi dồn dập các request đến endpoint.

Tài liệu Liên quan

• API Endpoints: Tài liệu tham khảo đầy đủ về tham số
• Error Handling: Tất cả các loại lỗi và phản hồi
• Troubleshooting: Các vấn đề thường gặp và cách khắc phục