문서 › 문제 해결 › 자주 발생하는 문제

자주 발생하는 문제

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

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

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

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

해결 방법: single 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 또는 Captcha 페이지

증상: API가 CAPTCHA 챌린지 또는 액세스 거부 페이지가 포함된 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 로테이션 시도 횟수를 늘리세요.

Timeout 오류

증상: request가 timeout 오류로 실패합니다.

원인: 대상 페이지가 설정된 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
  }'

browser request의 경우, checkText 값이 실제로 페이지에 나타나는지 확인하세요. 오타가 있으면 항상 timeout이 발생합니다.

429 Too Many Requests (RPM 제한)

증상: API가 "rate limit exceeded" 메시지와 함께 429 상태를 반환합니다.

원인: 분당 request 수(RPM) 제한을 초과했습니다. 이는 동시성 제한(아래 503 참조)과는 다릅니다.

해결 방법: response의 retryAfter 필드를 사용하여 재시도하기 전에 적절한 시간 동안 대기하세요:

import time
import requests

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:
            body = resp.json()
            wait = body.get("retryAfter", 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"}
)

Dashboard에서 현재 사용량을 확인하여 rate limit을 확인하세요.

503 Service Unavailable

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

원인: 이는 다음 두 가지 경우에 발생합니다:

  1. 동시성 제한 도달. 동시에 실행 중인 request가 너무 많습니다. 이는 분당 request를 제한하는 429와는 다릅니다. 503의 경우 RPM을 초과하지는 않았지만, 동시에 실행할 수 있는 request 수의 한계에 도달한 것입니다.
  2. 서비스 일시 중단. 유지보수 작업이 진행 중입니다.

두 경우 모두 response에 retryAfter 필드가 포함됩니다.

해결 방법: 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):
            body = resp.json()
            wait = body.get("retryAfter", 2 ** i)
            time.sleep(wait)
            continue
        return resp
    raise Exception("Request not resolved after retries")

503 동시성 제한에 자주 도달하는 경우, 스크래핑 파이프라인에서 병렬 request 수를 줄이거나 Dashboard에서 요금제의 동시성 제한을 확인하세요.

401 Authentication 오류

증상: 모든 request가 401 Unauthorized를 반환합니다.

체크리스트:

  1. header가 X-API-Key: YOUR_API_KEY인지 확인하세요 (Authorization: Bearer 또는 Api-Key가 아님)
  2. API key에 불필요한 공백이나 줄바꿈이 있는지 확인하세요
  3. 현재 key가 유출되었을 가능성이 있는 경우 Dashboard에서 새 key를 생성하세요

JSON 대신 예기치 않은 HTML 반환

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

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

해결 방법: 실제 브라우저 header처럼 작동하도록 Accept header를 추가하고 unblocker를 활성화하세요:

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 response를 자동으로 파싱하도록 할 수 있습니다.

여전히 해결되지 않으셨나요?

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

  1. 진행 중인 장애가 있는지 status page에서 확인하세요
  2. Dashboard에서 request 메트릭을 검토하세요
  3. request 상세 정보와 함께 support@foura.ai로 지원팀에 문의하세요

다음 단계

최근 업데이트: 2026년 4월 27일