Rate Limits

Всяка FourA API request преминава през rate limiting. Ще срещнете два типа лимити: concurrency (едновременни requests) и RPM (requests в минута). И двата се прилагат за всяка услуга.

Как работят Rate Limits

API налага лимити на две нива:

1. Глобален API лимит: прилага се за всички requests независимо от endpoint. Тази проверка се извършва първа.
2. Лимит за услуга: прилага се отделно за всеки endpoint (single, proxy, browser). Тази проверка се извършва само ако глобалният лимит е преминат успешно.

Ако глобалният лимит бъде достигнат, проверката за отделна услуга не се извършва. Дадена request трябва да премине и двете проверки, преди да достигне до backend.

Всяко ниво проследява две метрики:

• Concurrency: колко requests се изпълняват едновременно.
• RPM: колко requests сте изпратили през последните 60 секунди.

Rate Limit Responses

Когато достигнете лимит, API връща JSON response с текущото ви потребление и действащите лимити.

429: RPM Exceeded

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

Изпратили сте твърде много requests през последната минута. Изчакайте периода retryAfter, преди да изпратите още.

503: Concurrency Exceeded

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

Твърде много requests се изпълняват едновременно. Някои от предишните ви requests все още не са завършили.

Service Disabled

Когато дадена услуга е временно спряна за поддръжка, API връща 503 с различно съобщение за грешка:

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

Това не е rate limit. Услугата е временно недостъпна. Проверете стойността на retryAfter и опитайте отново след съответния брой секунди. Това обикновено се разрешава в рамките на няколко минути.

Не бъркайте това с 503 за concurrency. Отговор "Service disabled" няма да включва полетата current или limits.

Response Fields

Handling Rate Limits

Използвайте полето retryAfter, за да внедрите 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")

Съвети

• Проверявайте полетата current в rate limit responses, за да разберете моделите си на потребление.
• Ако постоянно достигате лимитите за concurrency, намалете броя на паралелните requests.
• Ако достигате лимитите за RPM, добавете малко закъснение между requests или ги групирайте в по-голям времеви прозорец.
• Стойността на retryAfter варира в зависимост от типа лимит: 2 секунди за concurrency, 5 секунди за RPM.
• Отговор "Service disabled" означава, че се извършва поддръжка. Не продължавайте да натоварвате endpoint.

Свързани теми

• API Endpoints: Пълен справочник за параметрите
• Error Handling: Всички типове грешки и отговори
• Troubleshooting: Често срещани проблеми и решения