모든 FourA API 요청은 엔진에 도달하기 전에 세 가지 검사를 거칩니다. 사용 중인 플랜의 제한, 전체 트래픽에 대한 플랫폼의 공유 허용량, 호출한 endpoint에 대한 플랫폼의 공유 허용량 순입니다. 각 검사는 자체적으로 요청을 거부할 수 있으며, 거부 시 서로 다른 응답 본문을 반환합니다.

순서대로 살펴보는 세 가지 검사

  1. 플랜 제한. 사용자의 플랜에서 허용하는 항목: 포함된 endpoint 및 파라미터, endpoint당 동시 실행 가능한 요청 수, 분당 요청 수, 일일 브라우저 요청 수, 결제 주기 내 사용 가능한 크레딧 및 대역폭.
  2. 글로벌 플랫폼 제한. 트래픽이 어떤 endpoint로 향했든 관계없이, 호출한 API 호스트가 해당 시점에 처리 중인 전체 트래픽입니다. 여기서 거부되면 "service": "api"(으)로 보고됩니다.
  3. Endpoint별 플랫폼 제한. 호출한 단일, proxy 또는 브라우저 서비스의 트래픽입니다.

사용자의 플랜이 가장 먼저 평가되며, 이러한 순서는 단순한 구현 세부 사항이 아닌 엄격한 규칙입니다. 공유 허용량은 공용 자원이므로 플랫폼에서 거부될 요청이 거부되는 과정에서 이 자원을 소모해서는 안 됩니다. 플랜 허용량을 초과하여 대량 요청을 보내는 특정 계정은 다른 사용자가 사용하는 자원에 영향을 미치기 전에 먼저 차단됩니다.

검사 2와 3은 사용자 트래픽이 아닌 FourA의 전체 트래픽을 집계합니다. 둘 중 하나에서 거부가 발생하면 "요청을 너무 많이 보냈음"이 아니라 "FourA 사용량이 많음"으로 해석하십시오. 검사 1은 사용자 계정에만 해당하며, 플랫폼의 다른 요소에 영향을 받지 않습니다.

공유 검사 중 하나에서 거부되면 요청이 백엔드에 도달하지 않았으므로 분당 버킷과 일일 브라우저 슬롯을 포함하여 진입 시 계산된 모든 계정 리소스가 반환됩니다. 또한 플랜이 아닌 FourA의 용량 문제로 거부되었으므로 분당 요청 수에 설명된 재시도 대기 시간에도 반영되지 않습니다.

POST /api/auto/은(는) 자체 슬롯을 보유하지 않습니다. 사용자를 대신해 수행되는 단일, Proxy, Browser 하위 호출은 다른 일반 요청과 마찬가지로 세 가지 검사를 모두 거치므로, 병렬로 실행되는 auto 호출 배치는 해당 하위 호출을 통해 플랜 사용량에 반영됩니다. (요청 수 및 성공률에는 auto 호출 자체가 1회로 계산되며, 하위 호출은 시도 횟수로 표시됩니다.)

플랜 제한

플랜 제한에 걸리면 호출을 거부한 제한 항목을 명시하는 X-FourA-Limit 헤더와 함께 응답합니다. 본문의 reason에도 동일한 코드가 포함되어 있으므로 헤더를 읽지 않고도 분기 처리가 가능합니다. 모든 플랜 제한 응답 본문에는 error, reason, documentation이(가) 포함되며, 나머지 필드는 제한 유형에 따라 달라집니다.

X-FourA-Limit 상태 소진된 항목
plan_limit_feature 403 호출한 endpoint 또는 exitCountries, exitState, exitCity, exitAsn, exitOs 파라미터가 플랜에 포함되어 있지 않음
plan_limit_premium 403 exitClass: premium 항목이 플랜에 포함되어 있지 않거나, Proxy request에 프리미엄 트래픽이 남지 않은 출구 위치가 지정됨
plan_limit_concurrency 429 해당 endpoint의 동시 request 한도
plan_limit_rate 429 해당 endpoint의 분당 request 한도
plan_limit_browser_daily 429 일일 브라우저 request 한도
plan_limit_credits 429 청구 주기 내 청구 크레딧 한도
plan_limit_bandwidth 429 청구 주기 내 대역폭 한도

각 제한 수치는 사용 중인 플랜에 따르며, 사용량 및 한도의 한도 및 기능 탭에서 실시간 사용량과 함께 확인할 수 있습니다. 이 값을 하드코딩하지 마십시오. 거부된 모든 응답에는 해당 요청을 거부한 한도 기준이 포함됩니다.

거부된 request는 크레딧을 소비하지 않습니다. 결과는 rate_limit이며, success에 대해서만 요금이 청구됩니다.

플랜에 포함되지 않은 endpoint 또는 파라미터

plan_limit_feature이 포함된 403 오류는 플랜에 포함되지 않은 항목을 요청했음을 의미합니다. 이 확인은 사용량이 집계되기 전에 실행되므로, 거부된 호출은 rate limit이나 일일 카운터에 영향을 주지 않습니다.

{
  "error": "The browser endpoint is not included in your plan (Free). Upgrade to use it.",
  "reason": "plan_limit_feature",
  "documentation": "https://foura.ai/prices"
}

위치 타겟팅 기능이 없는 플랜에서 exitCountries, exitState, exitCity, exitAsn 또는 exitOs을(를) 설정하는 POST /api/proxy/ 호출에도 동일한 코드와 상태가 반환됩니다. error 문자열에 해당 파라미터가 명시됩니다:

{
  "error": "Geo targeting (the exitCountries, exitState, exitCity, exitAsn and exitOs parameters) is not included in your plan (Free). Remove the parameter or upgrade.",
  "reason": "plan_limit_feature",
  "documentation": "https://foura.ai/prices"
}

plan_limit_premium 형태는 프리미엄 exit이 없는 플랜의 exitClass: premium에도 동일하게 적용됩니다. 프리미엄 exit을 포함하지만 이번 주기의 프리미엄 트래픽을 모두 소진한 플랜은 Proxy request가 특정 exit 위치를 지정하지 않는 한 거부되지 않습니다. 즉, 요청은 표준 풀에서 처리되며 response는 exitClass: standard를 보고합니다. 두 경우 모두 프리미엄 exit을 소진하지 않습니다. exitClass를 참고하십시오.

두 403 오류 모두 Retry-After를 설정하지 않습니다. 대기해도 결과는 달라지지 않습니다.

동시 요청

동시성은 endpoint별로 계산됩니다. 사용자의 플랜에는 Single, Proxy, Browser에 대해 각각 하나의 한도가 적용됩니다. 한도를 초과하는 request는 Retry-After: 1와 함께 429로 반환됩니다.

{
  "error": "Concurrency limit reached: your plan allows 50 simultaneous proxy request(s). Retry when an in-flight request finishes.",
  "reason": "plan_limit_concurrency",
  "documentation": "https://foura.ai/prices",
  "limit": 50,
  "in_flight": 51,
  "retry_after_seconds": 1
}

in_flight 거부된 request도 계산하므로 limit보다 최소 1개 더 많게 표시됩니다.

해결 방법은 무리하게 재시도하는 대신 자체 병렬 처리를 제한하는 것입니다. 429 응답에 대해 동일한 배치를 즉시 재전송하면 포함된 모든 호출에서 다시 429가 발생합니다. 작동 패턴은 병렬로 request 실행를 참고하십시오.

분당 Requests

Single 및 Proxy는 롤링 1분 단위로 측정되는 분당 허용량을 가집니다. 승인된 request만 여기에 포함됩니다. 거부된 request는 제외되므로 허용량을 약간 초과하여 지속적으로 요청하는 계정이라도 대부분 거부되는 것이 아니라 허용량만큼 처리됩니다.

{
  "error": "Rate limit reached: your plan allows 600 single requests per minute. Cool down and retry.",
  "reason": "plan_limit_rate",
  "documentation": "https://foura.ai/prices",
  "limit_per_minute": 600,
  "current_rate": 613,
  "retry_after_seconds": 17
}

retry_after_seconds은 그 사이에 다른 전송이 없을 경우 다음 request가 허용될 때까지 걸리는 대기 시간입니다. 최소 1초에서 최대 120초입니다. Retry-After header도 동일한 값을 전달합니다.

거부된 request를 이보다 빠르게 재시도할 때 적용되는 고유 규칙이 있습니다. 이동 1분 윈도우(sliding minute) 내에서 이 허용치로 인해 거부된 request 수가 허용치의 두 배를 초과하면, 호출이 거부되고 대신 30초 대기 상태가 적용됩니다.

{
  "error": "Rate limit cooldown: 1250 requests over your plan's 600 single requests per minute were refused in the last minute and kept arriving. Pause for 30 seconds.",
  "reason": "plan_limit_rate",
  "documentation": "https://foura.ai/prices",
  "limit_per_minute": 600,
  "current_rate": 540,
  "refused_last_minute": 1250,
  "cooldown": true,
  "retry_after_seconds": 30
}

일시 중지 중 거부된 요청은 카운트되지 않으므로, 클라이언트가 재시도를 계속하더라도 시간이 지나 분이 바뀌면 일시 중지는 자동으로 해제됩니다. 일시 중지 상태를 일반 허용량 제한과 구분하려면 error 텍스트 대신 cooldown 헤더를 확인하십시오.

일일 Browser 요청 수

Browser에는 분당 허용량이 없습니다. 플랜 한도는 UTC 자정부터 계산되는 일일 Browser 요청 수 기준이며, 측정기는 성공한 요청뿐만 아니라 승인된 모든 Browser 요청을 계산합니다. 503 Backend service unavailable처럼 크레딧 소진 없이 FourA 측에서 실패한 Browser 호출은 일일 슬롯을 반환합니다. 제한에 의해 거부되지 않은 Browser 및 Auto 응답은 X-FourA-Browser-Used-Today 및 X-FourA-Browser-Limit-Per-Day 헤더에 사용량과 한도를 포함합니다. 자세한 내용은 Response Headers를 참고하십시오.

{
  "error": "Daily browser limit reached: your plan allows 300 browser requests per day (resets at midnight UTC).",
  "reason": "plan_limit_browser_daily",
  "documentation": "https://foura.ai/prices",
  "limit_per_day": 300,
  "used_today": 301
}

대기 시간이 초 단위가 아닌 몇 시간 단위이므로, 이 거부 응답에는 retry_after_seconds 및 Retry-After header가 포함되지 않습니다. 작업을 중지하고 다음 실행을 자정 UTC로 예약하십시오.

청구 기간 크레딧

청구된 크레딧만 집계되며, 이는 성공한 request만 해당함을 의미합니다. 청구된 합계가 이번 기간에 사용 가능한 크레딧에 도달하면, 해당 기간이 초기화되거나 추가 구매를 할 때까지 추가 request가 거부됩니다.

{
  "error": "Credit limit reached: 75,000 of 75,000 credits used this billing period. Upgrade your plan or wait for the reset.",
  "reason": "plan_limit_credits",
  "documentation": "https://foura.ai/prices",
  "used": 75000,
  "hard_stop": 75000,
  "retry_after_seconds": 86400,
  "resets_at": "2026-10-01T00:00:00.000Z"
}

hard_stop은 해당 기간 동안 request가 중단되는 청구 크레딧 수입니다. 직접 계산하지 말고 body에서 읽으십시오. 요금제 외에 추가로 구매한 크레딧이 이미 포함되어 있습니다.

청구 기간 대역폭

대역폭 한도가 있는 요금제는 해당 기간의 표준 트래픽이 한도에 도달하면 request를 거부합니다. 프리미엄 트래픽에는 별도의 허용량이 적용되며 이 한도에 포함되지 않습니다. 추가 구매한 대역폭은 기본 포함 대역폭과 동일하게 취급되며, error 문자열에는 요금제 기본 제공량만이 아닌 실제 사용 가능한 총량이 표시됩니다.

{
  "error": "Bandwidth limit reached: 50 GB is available to you this billing period.",
  "reason": "plan_limit_bandwidth",
  "documentation": "https://foura.ai/prices",
  "used_bytes": 53687091200,
  "limit_bytes": 53687091200,
  "retry_after_seconds": 86400,
  "resets_at": "2026-10-01T00:00:00.000Z"
}

두 기간 제한 모두 retry_after_seconds은(는) 최대 24시간으로 제한되며, resets_at은(는) 기간이 갱신되는 정확한 시점입니다.

플랜 제한 필드

필드 유형 표시 대상 설명
error string 전체 적용 중인 수치를 포함한 사람이 읽을 수 있는 메시지
reason string 전체 plan_limit_ 및 제한 이름. X-FourA-Limit 헤더와 동일한 값입니다.
documentation string 전체 플랜 페이지 링크
retry_after_seconds number concurrency, rate, credits, bandwidth 대기 시간. Retry-After 헤더와 동일한 값입니다.
limit number concurrency 해당 endpoint에서 플랜이 허용하는 동시 request 수
in_flight number concurrency 거부된 건을 포함하여 현재 계정의 해당 endpoint에서 실행 중인 request 수
limit_per_minute number rate 해당 endpoint에서 플랜이 허용하는 분당 request 수
current_rate number rate 거부된 건을 포함하여 1분 이동 창에서 집계된 request 수
refused_last_minute number rate pause 1분 이동 창에서 분당 허용량에 의해 거부된 request 수. 30초 일시 중지 상태에서만 표시됩니다.
cooldown boolean rate pause 재시도가 너무 빨라 30초 동안 일시 중지된 경우 true입니다. 일반적인 분당 거부 시에는 포함되지 않습니다.
limit_per_day number browser daily 플랜이 허용하는 일일 browser request 수
used_today number browser daily 거부된 건을 포함하여 오늘 집계된 browser request 수
used number credits 이번 기간에 지금까지 청구된 크레딧
hard_stop number credits 이번 기간에 request가 중단되는 청구 크레딧 기준값
used_bytes number bandwidth 이번 기간에 지금까지 발생한 표준 트래픽(바이트 단위). 프리미엄 트래픽은 포함되지 않습니다.
limit_bytes number bandwidth 이번 기간에 사용 가능한 바이트 수
resets_at string credits, bandwidth 기간 종료 시점의 ISO 8601 타임스탬프

플랜 제한은 retry_after_seconds을(를) 사용합니다. 아래의 플랫폼 제한은 retryAfter을(를) 사용합니다. 재시도 헬퍼는 두 항목을 모두 읽거나, 플랜 제한 및 503 API key check temporarily unavailable(오류 참조)에서 설정되는 Retry-After 헤더를 읽어야 합니다.

플랫폼 제한

플랫폼 검사는 서비스별로 두 가지 항목을 추적하고, 전체 서비스에 걸쳐 한 가지 항목을 추가로 추적합니다.

  • Concurrency: FourA에서 동시에 실행 중인 request 수입니다.
  • RPM: 지난 60초 동안 FourA가 수신한 request 수입니다.

두 카운터 모두 해당 서비스를 사용하는 모든 사용자가 공유합니다. 아래 응답의 current 및 limits은(는) 사용자 계정이 아닌 플랫폼의 상태를 나타냅니다. 본인 계정의 수치를 확인하려면 플랜 제한 응답에서 in_flight을(를) 읽거나 대시보드에서 Usage & Limits를 확인하십시오.

429: RPM 초과

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

서비스의 지난 1분간 허용된 요청 수를 모두 소진했습니다. retryAfter초 동안 대기하십시오.

503: 동시성 한도 초과

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

서비스가 동시에 실행할 수 있는 최대 수의 요청을 처리하고 있습니다. 이 상태는 수 초 내에 해제됩니다.

서비스 비활성화됨

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

{
  "error": "Service disabled",
  "status": 503,
  "service": "single",
  "retryAfter": 60,
  "current": { "concurrency": 0, "rpm": 0 },
  "limits": { "maxConcurrency": 500, "maxRpm": 3000 }
}

이것은 rate limit이 아닙니다. 서비스를 일시적으로 사용할 수 없습니다. retryAfter 값을 확인하고 해당 초만큼 기다린 후 다시 시도하십시오. 일반적으로 수 분 내에 해결됩니다.

두 가지 503 형태 모두 동일한 키를 포함하므로, 필드 존재 여부가 아니라 error 문자열을 기준으로 분기하십시오. Service disabled은 유지보수 상태이고, Service at capacity는 동시성 초과입니다.

유지보수 형태에서 current.concurrency 및 current.rpm은 항상 0입니다. 아무것도 측정되기 전에 request가 거부되었습니다.

플랫폼 제한 필드

필드 타입 설명
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 서비스의 공유 동시성 허용량
limits.maxRpm number 서비스의 분당 공유 허용량

단일 헬퍼로 모든 거부 처리하기

대기할 가치가 있는 플랜 제한에는 Retry-After이 설정되어 있고, 해당 body에는 retry_after_seconds이 포함되어 있으며, 플랫폼 body에는 retryAfter이 포함되어 있습니다. 세 항목을 순서대로 읽고, 대기로 해결되지 않는 플랜 제한에서는 작업을 중단하십시오.

import time
import requests

# Plan limits that a short wait never clears.
STOP_ON = {
    "plan_limit_feature",
    "plan_limit_premium",
    "plan_limit_browser_daily",
    "plan_limit_credits",
    "plan_limit_bandwidth",
}

def wait_seconds(resp, attempt):
    header = resp.headers.get("Retry-After")
    if header and header.isdigit():
        return int(header)
    try:
        body = resp.json()
    except ValueError:
        return 2 ** attempt
    return body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** attempt

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

        limit = resp.headers.get("X-FourA-Limit")
        if limit in STOP_ON:
            raise RuntimeError(f"stopped by plan limit {limit}: {resp.json().get('error')}")

        if resp.status_code in (429, 503):
            time.sleep(wait_seconds(resp, attempt))
            continue

        return resp

    raise RuntimeError("Max retries exceeded")

일일 허용량은 몇 시간 동안 복구되지 않으며, 기간 허용량은 며칠 동안 복구되지 않으므로 대기하기보다는 중단으로 처리하십시오. 다음 실행을 예약하려면 본문에서 resets_at 값을 확인하십시오.

팁

  • 거부된 배치를 재시도하는 대신 진행 중인 request 수를 제한하십시오. 재시도 폭풍은 하나의 429를 여러 개로 만듭니다.
  • 먼저 X-FourA-Limit 값을 확인하십시오. 해당 제한이 본인 계정의 것인지 플랫폼의 것인지 하나의 문자열로 알려주며, 플랫폼 측 거부에서는 이 값이 설정되지 않습니다.
  • 수치를 하드코딩하지 마십시오. 모든 플랜 제한 response에는 거부 사유가 된 상한선이 포함되어 있으며, Usage & Limits에서 전체 목록을 확인할 수 있습니다.
  • 플랫폼 제한의 retryAfter 값은 유형별로 고정되어 있습니다. 동시성은 2초, RPM은 5초, 유지 관리는 60초입니다.
  • 두 종류의 503을 구분하려면 error 값을 매칭하십시오. 두 형태 모두 current 및 limits 필드를 포함하므로, 단순히 해당 필드의 존재 여부만 확인하면 유지 관리를 동시성 문제로 오인할 수 있습니다.
  • X-FourA-Limit가 포함된 403은 대상 사이트가 아니라 플랜에 관련된 문제입니다. 대상 사이트는 응답하지 않았습니다.

Proxy Port 전용 수치

위의 모든 내용은 JSON API에 해당합니다. proxy.foura.ai을 통해 전송하는 트래픽은 다른 단위의 별도 플랜 수치(동시 오픈 터널 수, 분당 터널 개방 수, 청구 기간 표준 트래픽)를 적용받습니다. CONNECT에는 본문이 없으므로, 이러한 거부는 JSON 본문 대신 X-Foura-Error header가 포함된 HTTP 상태로 전달됩니다. 상태 표는 Proxy Port를, 포트의 기가바이트가 차감되는 풀에 대한 정보는 How Your Plan Is Metered를 참조하십시오.

최근 업데이트: 2026년 11월 6일