본문으로 바로 가기

프록시 오류 코드

게이트웨이가 돌려주는 상태 코드별 의미와 흔한 원인, 조치 방법을 정리했습니다.

게이트웨이가 요청을 처리할 수 없을 때는 아래 상태 코드 중 하나와 함께 이유를 담은 JSON 본문 {"error":{"code":"…","message":"…"}}를 돌려줍니다. REST API의 오류와 같은 형태입니다. 그 외의 응답은 모두 목적지 사이트가 보낸 것이고, 게이트웨이는 손대지 않고 그대로 전달합니다. 사이트에서 온 403이나 429도 여기에 해당합니다. 게이트웨이가 읽을 수 없는 요청이나 인증까지 10초 넘게 걸린 요청은 응답 없이 연결을 닫고, 이미 열린 터널은 트래픽이 바닥나거나 프록시 유저가 비활성화·삭제되면 응답 없이 닫힙니다.

407 Proxy Authentication Required

게이트웨이가 이 연결이 어느 프록시 유저의 것인지 확인하지 못했습니다. 흔한 원인:

  • 비밀번호가 틀렸거나, 이미 교체된 비밀번호를 쓰고 있습니다.
  • 사용자명의 handle-name 부분이 계정의 프록시 유저와 일치하지 않습니다.
  • 타게팅 파라미터에 오타가 있거나, kr 외의 국가처럼 게이트웨이가 지원하지 않는 값을 넣었습니다.
  • IP가 화이트리스트에 없는데 자격 증명도 보내지 않았습니다.
  • 1분 안에 같은 주소(IPv4 주소 또는 IPv6 /64)에서 인증 실패가 20번을 넘었습니다. 이후 60초 동안은 비밀번호가 맞아도 같은 응답이 돌아옵니다.

해결 방법:

  • 대시보드에서 계정 식별자, 프록시 유저 이름, 비밀번호를 확인하세요.
  • 사용자명은 문서에 적힌 그대로 보내세요. 키는 대소문자를 가리지 않지만, 정의된 키여야 합니다.
  • 서버의 현재 공인 IP를 화이트리스트에 추가하거나, 자격 증명을 함께 보내세요.

비밀번호 추측 공격을 받는 동안의 인증 지연. 한 프록시 유저에 1분 안에 인증 실패가 10번을 넘으면(어느 주소에서 왔든), 게이트웨이는 그 프록시 유저의 비밀번호 확인을 한 번에 1분씩 늦춥니다. 이때 최근 24시간 안에 그 프록시 유저의 현재 비밀번호로 인증에 성공한 적이 없는 주소의 시도는 차례를 기다려야 합니다. 시도는 한 번에 하나씩 확인되고, 각 시도는 확인을 시작한 지 1초 뒤에 응답을 받습니다. 그래서 대량의 추측 시도 뒤에 줄을 서면 10초 제한에 걸려 응답 없이 닫힐 수 있습니다. 그 프록시 유저의 화이트리스트에 있는 주소에서 온 연결은 늦춰지지 않으며, 최근 24시간 안에 현재 비밀번호로 인증에 성공한 주소가 그 비밀번호를 다시 보내면 보통은 늦춰지지 않습니다. 새 주소에서 연결이 이렇게 멈춘다면 전에 인증에 성공한 주소로 접속하거나, 그 주소를 화이트리스트에 추가하세요. 화이트리스트는 어떤 경우에도 통합니다. 비밀번호가 유출됐을 수 있다면 공격이 멈춘 뒤 비밀번호를 교체하세요. 그러면 이전 비밀번호로 인증했던 주소도 모두 새 주소로 취급됩니다.

403 Forbidden

요청한 목적지가 허용되지 않습니다. 흔한 원인:

  • 목적지가 사설·예약 주소(127.0.0.1, 10.0.0.0/8, 169.254.169.254 등)이거나, 사설·미위임 이름(localhost, 그리고 .localhost, .local, .internal, .lan, .home, .corp, .intranet, .private, .home.arpa, .localdomain으로 끝나는 이름, 점이 없는 이름)이거나, 127.1 같은 비표준 IPv4 표기이거나, 메일 포트(25, 465, 587, 2525) 또는 0번 포트입니다.
  • 호스트명이 그런 주소로만 해석됩니다. 게이트웨이는 모든 호스트명을 직접 해석한 뒤 검사를 거친 주소로만 출구 IP를 연결하므로, 내부를 가리키는 이름(10.0.0.1.nip.io나 직접 만든 레코드)은 그 주소와 똑같이 거부됩니다.
  • 프록시 유저가 비활성 상태입니다.

해결 방법:

  • 공개된 호스트명이나 주소를 쓰고, 0, 25, 465, 587, 2525 외의 포트로 접속하세요.
  • 프록시 유저가 활성 상태인지 점검하세요.

이 응답은 인증을 통과한 요청, 즉 비밀번호가 맞거나 화이트리스트 주소에서 보낸 요청에만 돌아갑니다. 자격 증명이 틀리면 407로 응답하므로, 403으로 프록시 유저의 존재 여부가 드러나지는 않습니다.

402 Payment Required

이 연결에 쓸 트래픽이 남아 있지 않습니다. 흔한 원인:

  • 프록시 유저가 월 트래픽 한도에 도달했습니다.
  • 계정의 주거용 잔액이 모두 소진됐습니다(balance_exhausted). 무료 크레딧, GB 팩 잔량, 충전 크레딧이 모두 0입니다. 트래픽은 이 순서대로 차감됩니다.
  • 계정의 무료 크레딧이 아직 잠겨 있고, 그 밖에 주거용 트래픽을 결제할 잔액이 없습니다(verification_required). 새 계정의 무료 크레딧은 카드로 $1를 결제하거나(그 $1는 충전 크레딧으로 들어갑니다) 암호화폐로 $5 이상 결제해 계정을 인증하면 풀립니다. GB 팩과 충전 크레딧은 잠기지 않습니다.
  • isp-·dc- 연결이거나 해당 네트워크의 프록시 유저인데, 그 네트워크의 구독이 유효하지 않습니다(no active subscription for this network).

해결 방법:

  • 대시보드에서 프록시 유저의 한도를 올리거나 해제하세요.
  • 대시보드의 결제 메뉴에서 카드로 인증을 눌러 계정을 인증하면 무료 크레딧이 풀립니다. 결제 점검에서 그 결제가 보류되었다면, 대신 저희가 열어 드린 티켓에 답해 주세요.
  • 대시보드의 결제 메뉴에서 GB 팩을 구매하거나 크레딧을 충전하세요.
  • 결제 메뉴에서 해당 네트워크의 구독을 시작하거나 갱신하세요.
  • 한도 초기화를 기다리세요. 프록시 유저 한도는 매월 1일(UTC)에 초기화됩니다.

403과 마찬가지로 402도 인증을 통과한 요청에만 돌아가고, 자격 증명이 틀리면 407로 응답합니다.

429 Too Many Requests

계정이나 프록시 유저가 연결 수 제한을 넘었습니다. 흔한 원인:

  • 계정 전체에 열린 연결이 이미 2,000개이거나, 초당 새 연결이 200개(순간 최대 400개)를 넘었습니다(account rate limited).
  • 프록시 유저 하나에 열린 연결이 이미 1,000개이거나, 초당 새 연결이 100개(순간 최대 200개)를 넘었습니다(rate limited).

해결 방법:

  • 동시에 여는 연결 수를 줄이세요. 작업을 여러 프록시 유저로 나누는 것은 계정 한도(동시 2,000개, 초당 새 연결 200개)까지만 효과가 있습니다.
  • 백오프를 두고 재시도하고, HTTPS(CONNECT) 연결은 여러 요청에 재사용하세요. 평문 http:// 요청은 항상 요청마다 연결 하나를 씁니다.

502 Bad Gateway

게이트웨이가 출구 IP를 통해 요청을 완료하지 못했습니다. 흔한 원인:

  • 요청한 타게팅에 맞는 IP가 없습니다(예: 작은 도시와 ASN을 함께 지정한 경우).
  • 목적지가 출구 IP에서 온 연결을 거부했거나 끊었습니다.
  • 출구 IP가 30초 안에 응답하지 않았습니다.
  • 출구 IP가 게이트웨이의 연결을 거부했거나, 게이트웨이가 계정을 확인하지 못했습니다(proxy internal error).
  • 호스트명이 존재하지 않거나, 주소가 없거나, 네임서버가 응답하지 못했습니다(destination name did not resolve). 게이트웨이는 출구 IP를 고르기 전에 모든 호스트명을 직접 해석합니다.
  • ISP·데이터센터 구독은 유효하지만 아직 할당된 IP가 없습니다(no dedicated ip allocated). 할당된 IP는 결제 화면에서 확인할 수 있으며, 재시도가 아니라 IP가 할당되어야 해결됩니다.

해결 방법:

  • 타게팅 범위를 넓히거나, 그 조합에 해당하는 IP가 이 네트워크에 있는지 확인하세요.
  • 재시도하세요. 로테이션 유저는 다음 요청에서 새 IP를 받고, 스티키 세션은 새 세션 ID를 쓰면 됩니다.
  • no dedicated ip allocated라면 IP가 할당되어 결제 화면에 표시될 때까지 기다리세요.
  • destination name did not resolve라면 호스트명을 확인하세요. 호스트명이 맞다면 네임서버에 장애가 있을 수 있으니, 나중에 재시도하면 성공할 수 있습니다.

504 Gateway Timeout

게이트웨이가 호스트명을 제때 해석하지 못했습니다(destination name lookup timed out). 게이트웨이는 출구 IP를 고르기 전에 모든 호스트명을 직접 조회하며, 연결이 인증을 마쳐야 하는 10초 안에 응답할 수 있을 만큼 일찍 조회를 포기합니다.

해결 방법:

  • 잠시 기다렸다가 재시도하세요. 느린 네임 서버도 이후 시도에서는 대개 응답합니다.
  • 특정 호스트명에서 매번 타임아웃이 난다면 프록시 없이 그 호스트명의 DNS를 확인하세요.

522 Connection Timed Out

출구 IP는 골랐지만 목적지가 제때 응답하지 않았습니다. 흔한 원인:

  • 목적지가 느리거나 과부하 상태이거나, 출구 IP에서 온 트래픽을 응답 없이 버리고 있습니다.
  • 출구 IP가 목적지의 응답 시간 초과를 알려 왔습니다. 출구 IP 자체가 30초 안에 게이트웨이에 응답하지 않으면 522가 아니라 502입니다.

해결 방법:

  • 재시도하세요. 가능하면 다른 IP로 시도하는 것이 좋습니다.
  • 클라이언트 타임아웃은 게이트웨이가 출구 IP 하나를 기다리는 40초(연결 10초, 응답 30초)보다 짧게 설정해, 기다리는 시간을 직접 정하세요. 첫 출구 IP에 장애가 생기면 게이트웨이가 다른 출구 IP로 한 번 더 시도할 수 있습니다.
  • 특정 목적지에서 계속 타임아웃이 난다면 프록시 없이 접속해 보고 사이트 자체 문제인지 확인하세요.

게이트웨이 오류인지 사이트 오류인지 구분하기

게이트웨이가 만든 응답에는 오류 이름이 담긴 Proxy-Status 헤더(RFC 9209)와, error.code에 같은 오류를 담은 JSON 본문이 있습니다. 목적지에서 온 응답에는 이 헤더가 없습니다. HTTPS(CONNECT) 터널이 거절되면 curl을 비롯한 많은 클라이언트가 상태 코드만 보여 줍니다. curl -v로 실행하면 Proxy-Status를 포함한 헤더도 출력됩니다. 상태 코드만 보고 재시도하는 코드라면 먼저 이 헤더가 있는지 확인하세요. 게이트웨이가 보낸 403은 목적지가 차단됐다는 뜻이라 재시도해도 결과가 같지만, 사이트가 보낸 403은 다른 IP로 재시도하면 통과하는 경우가 많습니다.

HTTP/1.1 407 Proxy Authentication Required
Proxy-Status: scalardata; error=http_request_denied; details="unknown parameter: contry"
Proxy-Authenticate: Basic realm="scalardata"
Content-Type: application/json
Content-Length: 77
Connection: close

{"error":{"code":"unknown_parameter","message":"unknown parameter: contry"}}

details에 문제가 된 파라미터가 적히는 것은 인증을 통과한 요청, 즉 비밀번호가 맞거나 화이트리스트 주소에서 보낸 요청뿐입니다. 비밀번호가 틀렸거나 존재하지 않는 프록시 유저라면 사용자명에 다른 문제가 있더라도 항상 invalid credentials가 돌아옵니다.

SOCKS5에는 HTTP 상태 코드가 없고, 같은 상황이 SOCKS 응답 코드로 나타납니다. 인증에 실패하면 핸드셰이크가 끊기고, 게이트웨이가 거부한 요청(차단된 목적지, 비활성 프록시 유저, 트래픽 소진, 연결 수 제한)은 0x02(규칙상 불허), 게이트웨이 내부 오류는 0x01(일반 오류), 게이트웨이 바깥에서 생긴 실패(호스트명 해석 실패나 조회 타임아웃, 타게팅에 맞는 출구 IP 없음, 출구 IP 연결 실패, 목적지 타임아웃)는 0x04(호스트 도달 불가)로 돌아옵니다.

재시도 원칙

  • 407과 403은 재시도하지 마세요. 네트워크 상태가 아니라 설정 문제를 알리는 코드라서, 설정을 바꾸기 전까지는 같은 결과가 반복됩니다. 단, 인증 실패가 너무 많아 잠긴 경우의 407은 60초가 지나면 풀립니다.
  • 402도 상황이 바뀌기 전에는 재시도하지 마세요. GB 팩을 구매하거나 크레딧을 충전하거나 계정을 인증하거나 한도를 올리거나, ISP·데이터센터 네트워크의 구독을 시작하거나 갱신하거나, 매월 1일 한도 초기화 시점이 지나야 풀리고, 그 전에는 새 연결도 모두 같은 응답을 받습니다.
  • 502와 522는 새 IP로 재시도하세요. 로테이션 프록시 유저라면 요청을 다시 보내기만 하면 됩니다. 스티키 세션이라면 세션 ID를 바꿔서 같은 출구 IP로 다시 가지 않게 하세요. 단, no dedicated ip allocated는 재시도가 아니라 IP가 할당되어야 풀리고, destination name did not resolve는 먼저 호스트명을 확인한 뒤 호스트명이 맞을 때만 나중에 재시도하세요.
  • 504는 잠시 기다렸다가 재시도하세요. 게이트웨이가 호스트명을 제때 해석하지 못한 것이므로, 나중에 다시 조회하면 대개 성공합니다.
  • 429에는 백오프를 두세요. 재시도할 때마다 대기 시간을 조금씩 늘리세요. 한도는 시간이 지나면 저절로 풀리니, 어차피 거부될 연결을 계속 보내 게이트웨이에 부담을 줄 이유가 없습니다.
  • 클라이언트 타임아웃은 꼭 두세요. 클라이언트의 타임아웃이 먼저 발동해야, 멈춘 요청을 얼마나 기다릴지 스스로 정할 수 있습니다.

특정 목적지에서 IP를 여러 번 바꿔도 같은 코드가 계속 나오면, 프록시 유저 이름과 목적지, 발생 시각을 문의 페이지로 보내 주세요. 서비스 상태 페이지에서 해당 네트워크의 현재 상태도 확인하세요.