요청 결과
FourA API로 향하는 모든 request와 proxy 포트를 통과하는 모든 터널은 정확히 하나의 결과로 분류됩니다. 결과는 호출이 끝날 때 한 번 계산되며, 해당 호출을 실행한 credential에 기록됩니다. 대시보드, 활동 피드 및 결제 시스템은 모두 동일한 필드를 참조합니다.
오직 success 결과만 크레딧을 소모합니다. 프리미엄 트래픽은 크레딧과 별도로 집계되며 결과에 영향을 받지 않습니다. 결제 관련 안내를 참조하십시오.
7가지 결과
request가 도달할 수 있는 7가지 결과는 다음과 같습니다. 터널은 이 중 5가지를 사용합니다. 아래 터널의 동일한 용어 사용을 참조하십시오.
| 결과 | 레이어 | 의미 |
|---|---|---|
success |
해당 없음 | 유효한 response가 전달되었습니다. 청구 가능한 쿼터에서 차감됩니다. |
application_error |
target | 대상이 HTTP 200을 반환했으나 본문에 오류 필드가 포함되어 있거나, 본문이 FourA에서 감지한 봇 확인 또는 거부 페이지입니다. |
application_fail |
target | 대상이 validate 규칙에서 허용하지 않거나 validate를 전송하지 않은 200 이외의 상태 코드를 반환했거나, 대상 호스트 이름을 확인할 수 없는 경우를 포함하여 response를 전혀 반환하지 않았습니다. |
client_error |
caller | FourA를 벗어나기 전에 request가 거부되었습니다. 잘못된 매개변수, 형식에 맞지 않는 proxy 값, SSRF 보호 대상 URL 등이 원인입니다. |
rate_limit |
FourA | 실행되기 전에 request가 거부되었습니다. 플랜 제한(플랜에 포함되지 않은 endpoint 또는 매개변수에 대한 403, 허용량 소진에 따른 429) 또는 플랫폼의 공유 RPM/동시성 허용량 초과가 원인입니다. |
service_error |
FourA | 엔진이 서버 오류를 반환했거나 본문이 유효한 JSON이 아닙니다. |
service_fail |
FourA | FourA 자체 네트워크에 장애가 발생했습니다. 엔진이 제시간에 응답하지 않았거나 연결이 끊어졌거나, 클라이언트가 연결을 종료했습니다. |
레이어 열은 문제의 원인이 어디에 있는지 보여줍니다.
- target 결과는 호출 대상 사이트와 관련이 있습니다. request는 FourA에 정상적으로 도달했고, FourA 역시 대상에 정상적으로 도달했습니다. 대상 사이트 자체가 오류를 반환한 경우입니다.
- caller 결과는 request가 처리될 수 없는 상태였음을 의미합니다. request 형식을 수정하십시오.
- FourA 결과는 당사 측의 문제입니다. 재시도하고, 문제가 지속되면 상태 페이지를 확인하십시오.
대상 사이트가 403을 반환하면 client_error가 아니라 application_fail입니다. 호출 형식은 올바르며, 단지 해당 사이트가 요청을 거부한 것입니다.
실패한 호출의 형태
FourA에 도달하여 실행된 호출은 이후 어떤 상황이 발생하든 HTTP 200으로 반환됩니다. 데이터를 가져오기 전의 거부(400, 401, 403, 413, 429) 또는 FourA 측의 장애(5xx) 시에만 다른 HTTP 상태 코드를 사용합니다. 따라서 결과는 전송 상태 코드가 아니라 본문(body)을 통해 확인해야 합니다.
| Body | 발생한 상황 | 결과 |
|---|---|---|
status: 200, headers, data, error 없음 |
페이지가 성공적으로 전달되었습니다. | success |
200이 아닌 status, headers, data, error 없음 |
대상이 응답했으며 validate을(를) 전송하지 않았습니다. 응답 내용은 data에 있습니다. |
application_fail |
200이 아닌 status, headers, data 및 error |
대상이 응답했으나 validate 규칙에 의해 거부되었습니다(예: Status 404 is not in accept list 200). |
application_fail |
status: 200, headers, data 및 error |
대상이 HTTP 200으로 응답했으나 validate 규칙에 의해 거부되었습니다(예: Data not in accept list ["product"]). |
application_error |
error 및 total_time만 존재, status 없음, data 없음 |
대상이 HTTP로 응답하지 않았습니다. 리디렉션 제한 도달(Number of redirects hit maximum amount), 연결 또는 읽기 시간 초과, 연결 재설정, 또는 응답이 비어 있습니다. 해당 텍스트는 엔진 자체의 이유입니다. |
application_fail |
status: 0 및 error만 존재, 그 외 없음 |
호스트 이름을 확인할 수 없습니다: could not resolve <host>: <reason>. 어떤 엔진도 실행되지 않았으며, Auto에서는 meta이(가) 없습니다. DNS가 변경되기 전까지는 재시도해도 결과가 달라지지 않습니다. |
application_fail |
다섯 번째 행에 해당하는 리디렉션 루프:
{
"error": "Number of redirects hit maximum amount",
"total_time": 0.808
}
POST /api/proxy/의 경우 시도 횟수를 모두 소진한 호출은 error: Download maxTry limit reached 및 횟수가 포함된 attemptReport를 반환합니다(API Errors 참조). POST /api/auto/의 경우 실행 후 실패한 래더는 status, error, attempts, 원인이 포함된 attemptReport, 그리고 fail로 설정된 meta.rung을 반환합니다.
X-FourA-Credits는 실패 시에도 수행된 작업을 보고합니다. 결제는 success만 계산하므로 위와 같은 실패 형태는 비용이 청구되지 않습니다.
성공 판단은 validate를 인식합니다
validate가 없으면 API는 대상이 HTTP 200을 반환할 때만 요청을 success로 표시합니다.
validate를 사용하면 선언한 규칙에 따라 성공 여부가 결정됩니다. 특정 요청에 대해 200과 403을 모두 허용하도록 API에 지정하면 403 응답도 success로 반환됩니다. body는 변경 없이 그대로 전달됩니다.
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://target.example/feed",
"validate": {
"status": { "accept": [200, 403] }
}
}'
이 호출에서 403 응답은 success(으)로 계산되며 1개의 요청으로 청구됩니다. 500 응답은 application_fail(으)로 계산되며 청구되지 않습니다.
동일한 로직이 validate.headers 및 validate.data에도 적용됩니다. 엔진이 사용자의 규칙에 따라 수락한 모든 응답은 HTTP 상태와 관계없이 success(으)로 반환됩니다.
validate 사용 여부와 무관하게 절대 success이(가) 되지 않는 결과가 하나 있습니다. 시각적 인증 작업, 브라우저에 JavaScript 실행만 요청하는 페이지 등 FourA가 인식하는 봇 감지 페이지이거나 사이트가 HTTP 200으로 반환하는 거부 페이지인 HTTP 200 응답입니다. 해당 요청은 application_error(으)로 처리되며 청구되지 않습니다. 본문은 변경 없이 그대로 전달되며, X-FourA-Check-Page 헤더에 해당 페이지 이름이 표시됩니다.
과금 관련 영향
| 결과 | 과금 여부 | 할당량 반영 여부 |
|---|---|---|
success |
예 | 예 |
application_error |
아니요 | 아니요 |
application_fail |
아니요 | 아니요 |
client_error |
아니요 | 아니요 |
rate_limit |
아니요 | 아니요 |
service_error |
아니요 | 아니요 |
service_fail |
아니요 | 아니요 |
요청한 데이터를 정상적으로 전달한 요청에 대해서만 요금이 부과됩니다. FourA 측, 대상 측 또는 사용자 측의 실패는 모두 무료입니다.
이 표는 크레딧에 관한 내용입니다. 프리미엄 트래픽은 이와 별도로 계산됩니다. 결과와 관계없이 프리미엄 출구를 시도한 요청은 출구가 사용되었으므로 해당 시도에서 발생한 트래픽이 계산됩니다. 다른 출구가 응답하여 아직 실행 중이던 시도가 즉시 중단되더라도, 그때까지 발생한 트래픽은 계산에 포함됩니다.
표준 트래픽 역시 결과에 따르지 않습니다. 대역폭 제한이 있는 플랜에서는 모든 요청의 트래픽이 할당량에 반영됩니다. 사용자의 플랜 제한으로 인해 거부된 요청에는 트래픽이 계산되지 않습니다.
터널에서도 동일한 용어 사용
proxy 포트를 통한 터널도 이러한 결과 중 하나로 종료되므로, 단일 레이블 세트가 두 제품에 모두 적용됩니다. 7개 중 5개만 발생할 수 있는데, 이는 2개의 target 결과의 경우 FourA가 대상의 응답을 확인해야 하지만 터널의 응답은 사용자의 자체 암호화 트래픽이기 때문입니다.
| 결과 | 터널에서의 의미 |
|---|---|
success |
터널이 열렸고 사용자의 도구가 이를 수신함. |
client_error |
FourA가 해당 터널을 열지 않음: 사설 또는 예약된 주소이거나 지원하지 않는 포트임. |
rate_limit |
플랜 수치 중 하나에 도달했거나(동시 오픈 터널 수, 분당 터널 오픈 수, 해당 기간의 표준 트래픽, 보유하지 않은 프리미엄 트래픽), 포트 자체의 용량 또는 오픈 속도 제한에 도달함. |
service_error |
요청한 조건에 해당하는 FourA 출구가 없음. 대개 일시적임. |
service_fail |
FourA가 시도한 어떤 출구를 통해서도 대상에 연결할 수 없음: DNS, 타임아웃, 연결 거부. |
application_error |
터널에서는 절대 발생하지 않음. |
application_fail |
터널에서는 절대 발생하지 않음. |
거부 시에는 간단한 사유도 함께 제공되며 대시보드에는 당사 기준이 아닌 사용자 관점의 용어로 표시됩니다. FourA가 수용할 수 없는 옵션은 연결 자체에서 400로 응답되며 행을 기록하지 않으므로 여기에 전혀 표시되지 않습니다.
| 화면에 표시되는 사유 | 소진 내역 |
|---|---|
| port not in plan | 플랜에 해당 proxy 포트가 포함되지 않음 |
| tunnels at once | 플랜에서 허용하는 동시 터널을 모두 사용 중임 |
| openings per minute | 이번 분의 플랜 터널 오픈 횟수를 모두 소진함 |
| traffic used up | 해당 기간의 플랜 트래픽을 모두 소진함 |
| premium not available | 현재 플랜에서 프리미엄 트래픽을 사용할 수 없음 |
| port was full | 포트 자체의 용량 또는 오픈 속도가 한계에 도달함. 잠시 후 다시 시도하십시오. |
| port not served | FourA가 해당 포트로의 터널을 개방하지 않음 |
| private address | 사설 및 예약 주소에는 접근할 수 없음 |
터널은 청구할 request가 없으므로 크레딧으로 결제되는 항목이 없습니다. 포트는 대신 바이트 단위로 측정합니다. 플랜 측정 방식을 참고하십시오.
대시보드에서 결과 확인하기
API 키로 수행된 모든 request는 결과 라벨과 함께 Activity 피드에 표시됩니다. Metrics 및 Overview 페이지에서는 도넛 차트와 타임라인을 위해 동일한 필드를 집계합니다.
Activity를 결과별로 필터링할 때 단일 endpoint(Auto, Single, Proxy Finder, Browser)에 집중하여 특정 실패 유형이 특정 endpoint에 국한되는지 확인할 수도 있습니다. 페이지의 Product를 Proxy로 전환하면 동일한 결과 필터로 터널을 필터링할 수 있습니다.
재시도 휴리스틱
결과를 기반으로 한 1차 재시도 정책입니다.
| 결과 | 재시도 안전 여부 | 시점 |
|---|---|---|
success |
해당 없음 | response를 수신한 상태입니다. |
application_error |
경우에 따라 다름 | 대상의 오류 본문을 확인하십시오. 일부는 일시적이지만 대부분은 그렇지 않습니다. X-FourA-Check-Page가 설정되어 있다면 사이트에서 확인 페이지를 반환한 것입니다. 확인 페이지를 응답이 아닌 통과해야 할 단계로 처리하는 Auto로 URL을 전송하십시오. |
application_fail |
경우에 따라 다름 | 대상이 rate limit을 적용 중이라면 요청 속도를 늦추십시오. 대상이 차단 중이라면 Proxy 또는 Browser endpoint로 전환하십시오. |
client_error |
불가 | request가 동일한 방식으로 다시 실패합니다. 입력을 수정하십시오. |
rate_limit |
조건부 | response에 명시된 대기 시간(Retry-After, retry_after_seconds 또는 retryAfter)을 준수하십시오. plan_limit_browser_daily 발생 시 자정(UTC)까지 중단하고, plan_limit_credits 또는 plan_limit_bandwidth 발생 시 resets_at까지 중단하며, plan_limit_feature 또는 plan_limit_premium 발생 시에는 request를 수정하십시오. |
service_error |
가능 | 짧은 지수 백오프를 적용하십시오. |
service_fail |
가능 | service_error와 동일합니다. |
관련 항목
- API Errors: HTTP 수준 오류 응답
- Proxy Port: 터널 거부 시 반환되는 상태 코드
- Rate Limits:
rate_limit발생 조건 및 두 가지 반환 형태 - Metrics: 결과별 세부 분석 확인 위치
- Activity Log: request별 결과 내역