# Rate Limit

> URL: https://foura.ai/ko/docs/api/rate-limits
> Updated: 2026-11-06
> Index: https://foura.ai/llms.txt

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

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

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

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

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

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

`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에 프리미엄 트래픽이 남지 않은 [출구 위치](https://foura.ai/docs/api/endpoints#exit-location)가 지정됨 |
| `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 | 청구 주기 내 대역폭 한도 |

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

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

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

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

```json
{
  "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` 문자열에 해당 파라미터가 명시됩니다:

```json
{
  "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](https://foura.ai/docs/api/endpoints#exitclass)를 참고하십시오.

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

### 동시 요청

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

```json
{
  "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 실행](https://foura.ai/docs/how-to/run-requests-in-parallel)를 참고하십시오.

### 분당 Requests

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

```json
{
  "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초 대기 상태가 적용됩니다.

```json
{
  "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](https://foura.ai/docs/api/response-headers)를 참고하십시오.

```json
{
  "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가 거부됩니다.

```json
{
  "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` 문자열에는 요금제 기본 제공량만이 아닌 실제 사용 가능한 총량이 표시됩니다.

```json
{
  "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`([오류](https://foura.ai/docs/api/errors) 참조)에서 설정되는 `Retry-After` 헤더를 읽어야 합니다.

## 플랫폼 제한

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

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

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

### 429: RPM 초과

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

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

### 503: 동시성 한도 초과

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

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

## 서비스 비활성화됨

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

```json
{
  "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`이 포함되어 있습니다. 세 항목을 순서대로 읽고, 대기로 해결되지 않는 플랜 제한에서는 작업을 중단하십시오.

```python
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](https://foura.ai/docs/dashboard/quota)에서 전체 목록을 확인할 수 있습니다.
- 플랫폼 제한의 `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](https://foura.ai/docs/api/proxy-port#responses)를, 포트의 기가바이트가 차감되는 풀에 대한 정보는 [How Your Plan Is Metered](https://foura.ai/docs/guides/plans-and-metering)를 참조하십시오.

## 관련 문서

- [Run Requests in Parallel](https://foura.ai/docs/how-to/run-requests-in-parallel): 제한된 동시성 구현 패턴 예제
- [Usage & Limits](https://foura.ai/docs/dashboard/quota): 실시간 사용량과 함께 표시되는 모든 플랜 제한
- [API Endpoints](https://foura.ai/docs/api/endpoints): 전체 매개변수 레퍼런스
- [Error Handling](https://foura.ai/docs/api/errors): 모든 오류 유형 및 response
- [Response Headers](https://foura.ai/docs/api/response-headers): `X-FourA-Limit`, `Retry-After` 및 기타 header
- [Troubleshooting](https://foura.ai/docs/troubleshooting/common-issues): 일반적인 문제 및 해결 방법
