요청 결과

FourA API로의 모든 request는 정확히 하나의 outcome으로 분류되며, proxy 포트를 통한 모든 터널도 마찬가지입니다. outcome은 호출 종료 시 한 번 계산되어 이를 생성한 credential에 기록됩니다. 대시보드, 활동 피드, 결제 시스템 모두 동일한 필드를 읽습니다.

success에만 크레딧이 부과됩니다. 프리미엄 트래픽은 크레딧과 별도로 집계되며 outcome을 따르지 않습니다. Billing Implications를 참고하십시오.

The Seven Outcomes

request가 끝날 수 있는 7가지 outcome입니다. 터널은 이 중 5가지를 사용합니다. 아래의 Tunnels Use the Same Vocabulary를 참고하십시오.

Outcome	Layer	What it means
`success`	해당 없음	유효한 response가 전달되었습니다. 청구 가능한 쿼터에 반영됩니다.
`application_error`	target	대상이 HTTP 200을 반환했으나 body에 오류 필드가 포함되어 있거나, body가 FourA에서 인식하는 봇 감지 페이지입니다.
`application_fail`	target	대상이 `validate` 규칙에서 허용하지 않은 non-2xx를 반환했거나, 확인할 수 없는 대상 호스트 이름을 포함하여 response가 전혀 오지 않았습니다.
`client_error`	caller	FourA를 떠나기 전에 request가 거부되었습니다. 잘못된 파라미터, 유효하지 않은 proxy 값, SSRF 보호 URL이 해당합니다.
`rate_limit`	FourA	실행되기 전에 request가 거부되었습니다. 플랜 제한(플랜에 포함되지 않은 endpoint 또는 파라미터에 대한 403, 할당량 소진에 대한 429)이나 플랫폼의 공유 RPM 또는 동시성 한도에 의해 발생합니다.
`service_error`	FourA	엔진이 서버 오류로 응답했거나, body가 유효한 JSON이 아닙니다.
`service_fail`	FourA	FourA 자체 네트워크에 오류가 발생했습니다. 엔진이 제때 응답하지 않았거나 연결이 끊어졌거나, 사용자가 연결을 종료했습니다.

layer 열은 책임 소재를 나타냅니다.

target outcome은 호출한 사이트와 관련이 있습니다. request는 FourA에 정상적으로 도달했고, FourA도 대상에 정상적으로 도달했습니다. 대상 사이트 자체에서 오류를 반환했습니다.
caller outcome은 request가 실행될 수 없었음을 의미합니다. request 형식을 수정하십시오.
FourA outcome은 당사 측의 문제입니다. 재시도하고, 문제가 지속되면 status page를 확인하십시오.

대상 사이트가 403을 반환하는 것은 client_error이 아니라 application_fail입니다. 호출 형식은 올바랐으나, 사이트에서 거부한 것입니다.

Success Is `validate`-Aware

validate이 없으면 API는 대상이 HTTP 200을 반환할 때만 request를 success로 표시합니다.

validate를 사용하면 선언된 규칙에 따라 성공 여부가 결정됩니다. 특정 request에 대해 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 응답입니다. 해당 요청은 application_error이며 과금되지 않습니다. 본문은 변경 없이 그대로 전달되며, X-FourA-Check-Page 헤더에 해당 확인 페이지의 이름이 명시됩니다.

과금 관련 사항

결과	과금 여부	할당량 반영 여부
`success`	예	예
`application_error`	아니요	아니요
`application_fail`	아니요	아니요
`client_error`	아니요	아니요
`rate_limit`	아니요	아니요
`service_error`	아니요	아니요
`service_fail`	아니요	아니요

요청한 데이터를 성공적으로 전달한 요청에 대해서만 과금됩니다. FourA 측, 대상 측 또는 사용자 측의 실패는 모두 무료입니다.

위 표는 크레딧에 관한 내용입니다. 프리미엄 트래픽은 크레딧과 별도로 계산됩니다. 프리미엄 출구를 시도한 요청은 출구가 실제로 사용되었으므로 결과와 관계없이 해당 시도에서 발생한 트래픽을 집계합니다. 다른 출구가 응답하여 아직 실행 중이던 시도가 즉시 중단된 경우에도 그때까지 발생한 트래픽은 함께 계산됩니다.

표준 트래픽 역시 결과에 영향을 받지 않습니다. 대역폭 제한이 있는 플랜에서는 모든 요청의 트래픽이 해당 한도에 반영됩니다. 플랜 자체 한도로 인해 거부된 요청에는 트래픽이 집계되지 않습니다.

터널에도 동일한 용어가 사용됩니다

프록시 포트를 통한 터널도 이러한 결과 중 하나로 종료되므로 두 제품 모두 동일한 라벨 세트를 공유합니다. 단, 두 가지 target 결과는 FourA가 대상의 응답을 확인해야 하지만 터널의 응답은 사용자 자체의 암호화된 트래픽이므로 7가지 중 5가지만 발생할 수 있습니다.

결과	터널에서의 의미
`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는 outcome 라벨과 함께 Activity 피드에 표시됩니다. Metrics 및 Overview 페이지는 도넛 차트 및 타임라인을 위해 동일한 필드를 집계합니다.

Activity를 outcome별로 필터링할 때 단일 endpoint(Auto, Single, Proxy Finder, Browser)에 집중하여 특정 실패 유형이 특정 endpoint에만 발생하는지 확인할 수도 있습니다. 페이지의 Product를 Proxy로 전환하면 동일한 outcome 필터를 통해 터널 목록을 확인할 수 있습니다.

재시도 휴리스틱

outcomes 기반의 1차 재시도 정책:

Outcome	안전한 재시도 여부	재시도 시점
`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`	가능	짧은 지수 백오프(exponential backoff)를 적용하십시오.
`service_fail`	가능	`service_error`와 동일합니다.