문서 › API 레퍼런스 › Rate Limits

Rate Limits

모든 FourA API request는 rate limiting을 거칩니다. concurrency(동시 요청)와 RPM(분당 요청 수)이라는 두 가지 유형의 제한을 접하게 됩니다. 두 제한 모두 서비스별로 적용됩니다.

How Rate Limits Work

API는 두 가지 수준에서 제한을 적용합니다.

  1. Global API limit: endpoint에 관계없이 모든 request에 적용됩니다. 이 검사가 가장 먼저 실행됩니다.
  2. Per-service limit: 각 endpoint(single, proxy, browser)에 개별적으로 적용됩니다. 이 검사는 global limit을 통과한 경우에만 실행됩니다.

global limit에 도달하면 per-service 검사는 실행되지 않습니다. request가 백엔드에 도달하려면 두 가지 검사를 모두 통과해야 합니다.

각 수준에서는 두 가지 지표를 추적합니다.

  • Concurrency: 동시에 실행 중인 request 수입니다.
  • RPM: 지난 60초 동안 전송한 request 수입니다.

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
  }
}

지난 1분 동안 너무 많은 request를 전송했습니다. 추가 request를 보내기 전에 retryAfter 시간 동안 대기하십시오.

503: Concurrency Exceeded

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

동시에 너무 많은 request가 실행 중입니다. 이전 request 중 일부가 아직 완료되지 않았습니다.

Service Disabled

유지보수를 위해 서비스가 일시적으로 오프라인 상태가 되면 API는 다른 에러 메시지와 함께 503을 반환합니다.

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

이것은 rate limit이 아닙니다. 서비스를 일시적으로 사용할 수 없습니다. retryAfter 값을 확인하고 해당 초가 지난 후에 다시 시도하십시오. 이는 보통 몇 분 이내에 해결됩니다.

이를 concurrency 503과 혼동하지 마십시오. "Service disabled" response에는 current 또는 limits 필드가 포함되지 않습니다.

Response Fields

필드 타입 설명
error string 사람이 읽을 수 있는 에러 메시지
status number HTTP 상태 코드 (429 또는 503)
service string 제한에 도달한 서비스: single, proxy, browser 또는 api
retryAfter number 재시도하기 전에 권장되는 대기 시간(초)
current.concurrency number 현재 활성화된 request 수
current.rpm number 지난 60초 동안의 request 수
limits.maxConcurrency number 허용되는 최대 동시 request 수
limits.maxRpm number 허용되는 분당 최대 request 수

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")

Tips

  • rate limit response의 current 필드를 확인하여 사용 패턴을 파악하십시오.
  • concurrency 제한에 지속적으로 도달하는 경우 병렬 request 수를 줄이십시오.
  • RPM 제한에 도달하는 경우 request 사이에 짧은 지연 시간을 추가하거나 더 긴 기간에 걸쳐 배치로 처리하십시오.
  • retryAfter 값은 제한 유형에 따라 다릅니다. concurrency의 경우 2초, RPM의 경우 5초입니다.
  • "Service disabled" response는 유지보수가 진행 중임을 의미합니다. endpoint에 계속해서 요청을 보내지 마십시오.
최근 업데이트: 2026년 4월 15일
← API 오류 Inspect Endpoint →