자주 발생하는 문제

FourA API 사용 시 가장 자주 발생하는 문제에 대한 해결 방법입니다.

비어 있거나 불완전한 콘텐츠

증상: API가 200 상태 코드를 반환하지만 data 필드가 비어 있거나 예상된 콘텐츠가 누락됩니다.

원인: 대상 페이지가 초기 페이지 로드 후 JavaScript를 사용하여 콘텐츠를 렌더링합니다.

해결 방법: 단일 endpoint에서 browser endpoint로 전환합니다. checkText를 사용하여 콘텐츠가 로드되었는지 확인합니다.

curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/products",
    "timeout_ms": 15000,
    "checkText": "product-list"
  }'

참고: browser endpoint는 콘텐츠를 data 필드가 아닌 body 필드로 반환합니다.

403 Forbidden 또는 인증 페이지

증상: API가 인증 페이지 또는 접근 거부 페이지가 포함된 HTML을 반환합니다.

원인: 대상 사이트가 request를 자동화된 것으로 감지하여 차단했습니다.

해결 방법: 자동 IP 순환을 위해 proxy endpoint를 사용하십시오:

curl -X POST https://eu.api.foura.ai/api/proxy/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "maxTries": 5,
    "request": {
      "method": "GET",
      "url": "https://example.com/prices",
      "unblocker": true
    }
  }'

문제가 지속되면 maxTries 값을 늘려 proxy 순환 재시도 횟수를 늘리십시오.

대상 서버가 반환한 403은 본문 내에 status: 403를 포함한 HTTP 200으로 수신됩니다. X-FourA-Limit header를 동반한 호출 자체의 403 오류는 다른 문제입니다. 플랜에 포함되지 않은 403 오류를 참고하십시오.

시간 초과 오류

증상: timeout 오류와 함께 request가 실패합니다.

원인: 대상 페이지를 로드하는 데 설정된 timeout보다 오랜 시간이 걸립니다.

해결 방법: timeout_ms 값을 늘리십시오 (기본값은 single 15초, browser 30초, proxy 45초):

curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://slow-site.com",
    "timeout_ms": 60000
  }'

브라우저 요청의 경우 checkText 값이 페이지에 실제로 나타나는지도 확인하십시오. 오타가 있으면 checkText:<your text> not found 오류와 함께 호출이 실패합니다.

403 요금제 미포함

증상: API가 X-FourA-Limit 헤더 및 plan_limit_feature 또는 plan_limit_premium의 reason와 함께 403을 반환합니다.

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

원인: 호출한 endpoint 또는 전송한 parameter가 플랜에 포함되어 있지 않습니다. plan_limit_feature는 제외된 endpoint와 지리적 타겟팅이 없는 exitCountries, exitState, exitCity, exitAsn 또는 exitOs에 적용됩니다. plan_limit_premium은 프리미엄 출구가 없는 exitClass: premium, 그리고 프리미엄 트래픽을 모두 소진한 후 출구 위치를 지정하는 Proxy request에 적용됩니다. 대상 서버에 연결되지 않았으며 크레딧도 소모되지 않았습니다.

해결 방법: parameter를 제거하거나, 플랜에 포함된 endpoint를 호출하거나, 플랜을 업그레이드하세요. 사용량 및 한도의 한도 및 기능 탭에서 플랜에 포함된 항목을 확인할 수 있습니다. 변경 없이 재시도하지 마세요. 대기해도 결과가 달라지지 않으므로 Retry-After는 설정되지 않습니다.

429 너무 많은 요청

증상: API가 429를 반환합니다.

원인: 두 가지 검사 중 하나로 인해 호출이 거부되었으며, response에서 원인을 확인할 수 있습니다. X-FourA-Limit header가 포함되어 있다면 해당 endpoint의 동시 request 수 또는 분당 request 수, 일일 Browser request 수, 결제 주기의 크레딧 또는 대역폭 등 플랜 한도 중 하나에 도달한 것입니다. 해당 header가 없다면 해당 서비스에 대한 플랫폼의 공유 분당 허용량이 가득 찬 상태이며, 이는 사용자의 트래픽이 아닌 FourA의 전체 트래픽과 관련된 문제입니다.

해결 방법: 먼저 X-FourA-Limit를 확인하세요. 한도 해제까지 몇 초 남지 않은 경우에는 대기하고, 그렇지 않은 경우에는 중단하세요. 대기로 해결되는 플랜 한도의 경우 남은 시간(초)이 Retry-After header와 retry_after_seconds에 표시되며, 공유 한도의 경우 retryAfter에 표시됩니다.

import time
import requests

# Plan limits that come back in hours or days, not seconds.
STOP_ON = {"plan_limit_browser_daily", "plan_limit_credits", "plan_limit_bandwidth"}

def make_request(endpoint_url, payload, retries=3):
    for i in range(retries):
        resp = requests.post(
            endpoint_url,
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json=payload
        )
        if resp.status_code == 429:
            limit = resp.headers.get("X-FourA-Limit")
            if limit in STOP_ON:
                raise Exception(f"stopped by {limit}: {resp.json().get('error')}")
            header = resp.headers.get("Retry-After")
            body = resp.json()
            wait = (
                int(header) if header and header.isdigit()
                else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** i
            )
            time.sleep(wait)
            continue
        return resp
    raise Exception("Rate limit not resolved after retries")

# Example: single request
make_request(
    "https://eu.api.foura.ai/api/single/",
    {"method": "GET", "url": "https://example.com"}
)

헤더에 plan_limit_concurrency 또는 plan_limit_rate가 표시된 경우, 해결 방법은 재시도를 무리하게 반복하는 대신 동시 호출 수와 분당 시작하는 호출 수를 제한하는 것입니다. 거부된 배치를 즉시 다시 보내면 전체 배치가 다시 거부됩니다. 거부된 호출은 분당 한도에 포함되지 않지만, 해당 한도의 두 배를 초과하여 계속 유입되면 거부가 쿨다운으로 전환됩니다. 429 본문에 cooldown: true가 포함되고 30초 동안 일시 중지(retry_after_seconds: 30)하도록 요청합니다. Run Requests in Parallel에서 관련 패턴을 확인할 수 있으며, 대시보드의 Usage & Limits에서 한도와 함께 실시간 카운터를 확인할 수 있습니다.

503 서비스를 사용할 수 없음

증상: API가 503 상태를 반환합니다.

원인: 다음 세 가지 경우에 발생합니다.

  1. 서비스 용량 초과. FourA가 해당 엔진에서 동시에 실행할 수 있는 최대 요청 수에 이미 도달했습니다. 이는 개별 트래픽이 아닌 전체 트래픽 기준으로 계산됩니다. error 필드에 Service at capacity가 표시됩니다. 보통 몇 초 내에 해결됩니다.
  2. 서비스 일시 비활성화. 정기 점검이 진행 중입니다. error 필드에 Service disabled가 표시됩니다.
  3. 일시적으로 FourA가 키를 확인할 수 없음. error 필드에 API key check temporarily unavailable와 함께 Retry-After: 5가 표시됩니다. 키 자체에는 문제가 없습니다.

세 경우 모두 응답에 retryAfter 필드가 포함됩니다. 세 경우 모두 플랜 한도 초과가 아닙니다. 개별 플랜 한도는 503이 아닌 403 또는 429의 X-FourA-Limit 헤더로 항상 응답합니다.

해결 방법: retryAfter초 동안 기다린 후 다시 시도하십시오.

import time
import requests

def make_request_with_retry(endpoint_url, payload, retries=3):
    for i in range(retries):
        resp = requests.post(
            endpoint_url,
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json=payload
        )
        if resp.status_code in (429, 503):
            header = resp.headers.get("Retry-After")
            body = resp.json()
            wait = (
                int(header) if header and header.isdigit()
                else body.get("retry_after_seconds") or body.get("retryAfter") or 2 ** i
            )
            time.sleep(wait)
            continue
        return resp
    raise Exception("Request not resolved after retries")

용량 초과로 인한 503 오류는 FourA 시스템이 사용 중임을 의미하므로, 백오프 후 재시도하는 것이 해결책의 전부입니다. 대신 429 및 X-FourA-Limit 응답으로 거부된다면 사용자 측 원인입니다. 파이프라인의 병렬 request 수를 줄이십시오.

504 업스트림 시간 초과

증상: API가 {"error": "Upstream timeout"}와 함께 504를 반환합니다.

원인: request에 설정한 시간 제한 내에 작업이 완료되지 않았습니다. 대상 사이트의 지연, 콜드 상태의 챌린지 해결, 또는 매우 큰 페이지 크기 등이 원인이 될 수 있습니다. API 키, 매개변수, proxy 설정의 문제는 아닙니다.

해결 방법: 호출에 더 많은 시간을 부여하거나 재시도하십시오. FourA는 설정된 timeout_ms 값에 약간의 여유 시간을 더해 대기하므로, 이 값을 늘리면 대기 시간이 실제로 연장됩니다.

{
  "url": "https://slow-site.com/report",
  "timeout_ms": 90000
}

보호된 대상에 대한 /api/auto/의 경우, 콜드 스타트 상태의 첫 호출은 수십 초가 걸릴 수 있습니다. 해당 timeout_ms는 전체 단계를 포함하며 최대 180000까지 허용합니다.

/api/auto/ 자체가 해당 예산을 모두 소진하더라도 호출은 여전히 HTTP 200으로 응답합니다. 본문에는 time budget exhausted로 시작하는 error가 포함되며, status은 보통 504입니다 (이전에 실패한 시도가 대신 자체 상태를 남길 수 있습니다). timeout_ms를 늘리거나 다시 시도하십시오.

502 업스트림을 사용할 수 없음

증상: API가 {"error": "Upstream unavailable"}와 함께 502를 반환하거나 {"error": "Backend service unavailable"}와 함께 503을 반환합니다.

원인: 대체로 인스턴스 재시작으로 인해 FourA가 자체 엔진에 연결할 수 없었거나(Upstream unavailable), 엔진이 사용 가능한 응답을 반환하지 않았습니다(Backend service unavailable). /api/browser/에서는 모든 브라우저가 사용 중일 때 페이지가 사용 가능한 브라우저를 최대 10초 동안 대기하며, 그 후에도 계속 대기 중인 페이지는 이 503 오류로 반환됩니다.

해결 방법: 짧은 대기 시간 후 재시도하십시오. 둘 다 service_error로 분류되며 success만 과금되므로 재시도 시 추가 비용이 발생하지 않습니다. 1~2분 이상 지속되면 상태 페이지를 확인하십시오.

401 인증 오류

증상: 모든 요청이 401 Unauthorized를 반환합니다.

체크리스트:

  1. 헤더가 X-API-Key: YOUR_API_KEY인지 확인 (Authorization: Bearer 또는 Api-Key이 아님)
  2. API 키에 불필요한 공백이나 줄바꿈이 있는지 확인
  3. 현재 키가 유출되었을 가능성이 있는 경우 대시보드에서 새 키 생성

400 잘못된 요청

증상: POST /api/single/, /api/proxy/ 또는 /api/browser/ 호출이 {"error": "Invalid request: <field>: <reason>; ..."}와 함께 400을 반환합니다.

원인: 요청 본문의 필드가 누락되었거나, 유형이 잘못되었거나, 범위를 벗어났습니다. 메시지에는 허용할 수 없는 각 필드와 그 이유가 최대 5개까지 나열되며, 그 외 항목이 있는 경우 and N more가 뒤따릅니다. 가져온 데이터가 없고 결과는 client_error이며 크레딧은 차감되지 않습니다.

해결 방법: 지정된 필드를 수정한 후 요청을 다시 전송하십시오. 동일한 본문은 동일한 400 오류를 수신하므로 본문을 변경하지 않고 재시도하지 마십시오. 엔드포인트 레퍼런스에 모든 필드의 유형과 제한 사항이 나열되어 있습니다. /api/auto/에서는 동일한 실수가 status: 400 및 error의 사유와 함께 HTTP 200으로 반환됩니다.

400 대상이 사설 또는 예약된 IP로 확인됨

증상: 요청이 FourA를 떠나기 전에 API가 Refusing to fetch <target>: target resolves to a private or reserved IP range와 함께 400을 반환합니다.

원인: 대상 url가 사설, 루프백 또는 예약된 IP 범위(RFC 5735, RFC 6598 또는 IPv6 예약 블록)로 확인됩니다. FourA는 내부 호스트에 접근하는 데 네트워크가 사용되지 않도록 이러한 대상을 거부합니다.

해결 방법: 퍼블릭 URL을 가져오십시오. 테스트 중이라면 https://example.com 또는 https://httpbin.org/get와 같은 퍼블릭 대상을 사용하십시오. 의도한 대상이 직접 운영하는 서비스인 경우 먼저 퍼블릭 호스트 이름으로 노출하십시오.

{ "error": "Refusing to fetch <target>: target resolves to a private or reserved IP range. The FourA scraping API only forwards requests to public internet hosts." }

조회할 수 없는 호스트 이름은 거부되지 않습니다. FourA가 도달할 수 없는 다른 대상과 마찬가지로 호출은 status: 0 및 사유(could not resolve <host>: <reason>)와 함께 HTTP 200으로 반환되며, 요금이 청구되지 않습니다.

400 URL 내 공백

증상: Single, Proxy 또는 Auto 모드에서 요청이 FourA를 벗어나기 전에 invalid URL: it contains a space; encode it as %20 (the URL as sent: "...")와 함께 400을 반환합니다.

원인: URL 내부에 공백이나 제어 문자가 포함되어 있습니다. 주로 페이지에 표기된 링크를 그대로 가져온 경우 발생합니다(javascript: void(0), 텍스트가 포함된 공유 링크 등). 아무것도 가져오지 않으며 결과는 client_error이고 크레딧은 소모되지 않습니다.

해결 방법: 전송하기 전에 URL을 인코딩하고(공백은 %20), javascript: 링크와 같이 웹페이지가 아닌 링크는 건너뛰십시오. Browser 모드는 이러한 URL을 Chrome과 동일한 방식으로 가져옵니다.

400 대상이 FourA API 자체임

증상: 요청이 FourA를 벗어나기 전에 API가 Refusing to fetch <url>: that is the FourA API itself, not a page.와 함께 400을 반환합니다.

원인: url 매개변수가 api.foura.ai 또는 eu.api.foura.ai을 가리킵니다. 크롤러가 페이지의 상대 링크를 해당 페이지 자체의 URL 대신 API URL을 기준으로 확인할 때 주로 발생하므로, /category/news/가 https://eu.api.foura.ai/category/news/로 변환됩니다. 아무것도 가져오지 않으며 크레딧은 소모되지 않습니다.

해결 방법: 요청을 보내기 전에 모든 링크를 출처 페이지의 URL 기준으로 확인하십시오(예: Python의 urljoin(page_url, href) 사용). Inspect endpoint(/inspect)는 FourA를 통해 가져올 수 있는 API 호스트의 유일한 주소입니다.

exitCountries 사용 시 no_eligible_proxy

증상: exitCountries를 포함한 /api/proxy/ 호출이 JSON 오류 엔벨로프와 함께 HTTP 200을 반환합니다.

{
  "error": "No eligible proxy found for exit countries: CZ, GB",
  "code": "no_eligible_proxy",
  "details": { "exitCountries": ["CZ", "GB"] },
  "total": 0.084
}

원인: 현재 proxy 풀에 대상에 표시되는 국가가 허용 목록과 일치하는 정상 exit가 없습니다. 표준 풀은 exitCountries 설정 시 요청되지 않은 국가로 절대 대체되지 않습니다. exitCountries가 없으면 동일한 상황에서 {"error": "Failed"}(으)로 응답합니다. FourA에서 시도할 exit가 없으므로 몇 초 후 다시 시도하십시오.

exit 위치(exitState, exitCity, exitAsn, exitOs 또는 exitLifetimeMin, exitClass: premium 포함)를 지정한 request는 프리미엄 exit를 통해서만 전송됩니다. FourA에 시도할 수 있는 프리미엄 exit가 남아 있지 않으면 호출이 "error": "No premium exit answered for this request" 및 동일한 code: no_eligible_proxy(으)로 종료됩니다.

해결 방법: 요청된 범위를 유지하고 나중에 다시 시도하십시오. 풀은 약 10분마다 새로고침되므로, 현재 일치하는 항목이 없는 국가도 1시간 이내에 사용 가능해지는 경우가 많습니다.

import time, requests

def fetch_scoped(url, countries, max_attempts=6, wait_sec=600):
    for _ in range(max_attempts):
        r = requests.post("https://eu.api.foura.ai/api/proxy/",
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json={"maxTries": 5, "exitCountries": countries,
                  "request": {"method": "GET", "url": url}}).json()
        if r.get("code") == "no_eligible_proxy":
            time.sleep(wait_sec)
            continue
        return r
    raise RuntimeError(f"no eligible exit in {countries} after {max_attempts} attempts")

워크플로의 국가 요구사항이 실제로 변경된 경우에만 국가 목록을 넓히십시오. 다른 국가로 자동 대체(fallback)되면 다운스트림의 지리적 종속 로직이 손상될 수 있습니다.

브라우저 프로필이 거부됨

증상: 호출 결과로 unknown profile '<id>', no profile matches browser=... 또는 browser profile selection requires unblocker:true가 반환됩니다.

원인: 전송한 profile, browser, os 또는 version가 카탈로그에 없거나, unblocker: false와(과) 함께 전송되었습니다.

해결 방법: 최신 카탈로그는 GET /api/profiles에서 확인하여 선택하고, 브라우저를 선택할 때는 unblocker를 켜두십시오.

응답 본문이 깨진 텍스트로 반환됨

증상: 대상 사이트가 비 UTF-8 문자 집합을 사용할 때 응답 data(또는 body)에 모지바케(문자 깨짐)나 읽을 수 없는 문자가 포함됩니다.

원인: 기본적으로 FourA는 대상 사이트의 Content-Type 헤더 또는 HTML <meta charset> 태그를 기반으로 응답 본문을 UTF-8로 자동 디코딩합니다. 대상 사이트의 문자 집합 정보가 잘못되었으면 깨진 텍스트가 반환됩니다.

해결 방법: 바이너리 페이로드(이미지, protobuf, 원시 오디오 등)의 경우 요청에 returnBuffer: true를 설정하십시오. 그러면 Single 및 Proxy는 문자 집합 트랜스코딩 없이 원시 바이트를 포함하는 객체인 data({"type": "Buffer", "data": [<byte values>]})를 반환합니다.

{
  "method": "GET",
  "url": "https://example.com/image.png",
  "returnBuffer": true
}

문자 집합(charset)이 잘못 선언된 텍스트 대상의 경우 raw 바이트를 직접 디코딩하세요. returnBuffer: true(으)로 가져온 다음 data.data에서 바이트 값을 읽고 올바른 charset으로 디코딩합니다.

JSON 대신 예기치 않은 HTML이 반환됨

증상: 대상 사이트에서 JSON을 예상했으나 HTML을 수신했습니다.

원인: 대상 페이지가 header에 따라 다른 콘텐츠를 제공할 수 있습니다.

해결 방법: Accept header를 추가하고 unblocker을(를) 활성화하여 실제 브라우저와 유사한 header를 전송하세요.

curl -X POST https://eu.api.foura.ai/api/single/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "url": "https://api.example.com/data",
    "headers": [["Accept", "application/json"]],
    "unblocker": true
  }'

tryJsonData를 true로 설정하여 FourA가 JSON 응답을 자동으로 파싱하도록 할 수도 있습니다.

본문이 콘텐츠가 아닌 챌린지 페이지인 경우

증상: 호출이 성공했고 status이 200이지만, data(또는 body)가 원하는 페이지 대신 봇 확인 페이지로 반환됩니다.

원인: 대상 사이트에서 봇 확인을 실행했으며, FourA가 이를 감지했으나 통과하지 못했습니다. 응답에 관련 정보가 명시됩니다. Single 및 Proxy는 solved: false와 함께 defense를 반환하고, Browser는 defenses.present에 벤더 정보를 포함한 defenseSolved: false을 반환합니다.

해결 방법: 먼저 defense.vendor을 확인한 다음 단계를 상향 조정하십시오. Single에서 다른 브라우저 프로필을 시도하거나, Proxy로 전환하여 다른 출구 IP를 사용하거나, JavaScript가 실행되도록 Browser를 사용하십시오. 전체 필드 참조 및 벤더 목록: 사이트 확인.

실제 페이지만 포함하는 validate.data.accept 하위 문자열을 추가하십시오. FourA가 인식한 확인 페이지는 성공으로 처리되지 않습니다. 이는 X-FourA-Check-Page 헤더와 함께 반환되며 요금이 청구되지 않습니다. validate이 없으면 FourA가 인식하지 못한 확인 페이지가 HTTP 200으로 반환될 때 성공으로 간주되어, 호출 시점이 아닌 다운스트림에서 문제를 발견하게 됩니다.

여전히 문제가 해결되지 않나요?

위의 해결 방법으로 문제가 해결되지 않는 경우:

  1. 진행 중인 인시던트가 있는지 상태 페이지에서 확인하십시오.
  2. 대시보드에서 요청 지표를 검토하십시오.
  3. 요청 세부 정보(실패한 응답의 X-FourA-Request-Id 포함)를 첨부하여 support@foura.ai로 지원 팀에 문의하십시오.

다음 단계

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