CAPTCHA 작업 폴링 및 시간 초과 처리하기

waitMs는 API 요청이 응답하기 전에 결과를 기다리는 시간을 제어합니다. 작업 JSON의 필드가 아니라 URL 쿼리 매개변수입니다. 생성 시 기본값은 제품마다 다르며 GET 폴링에는 별도의 한도가 있습니다.

요청한 서버 대기 시간에 네트워크 오버헤드를 더한 만큼 HTTP 클라이언트에 충분한 시간을 주세요. 클라이언트 제한 시간이 서버 대기 시간보다 짧으면 작업의 현재 상태를 받기 전에 응답이 중단될 수 있습니다.

공식 SDK의 solve 메서드는 작업을 한 번 생성하고 준비된 결과가 나오거나 오류가 발생할 때까지 폴링합니다. Python은 초 단위의 timeout과 poll_interval을 제공하며, Node.js는 밀리초 단위의 timeoutMs와 pollIntervalMs를 제공합니다. 문서에 나온 설정은 해결 기한 3분과 폴링 간격 1초를 사용합니다.

직접 제어하려면 Python의 create_task와 get_task, Node.js의 createTask와 getTask를 사용하세요. 다음 순서로 진행하세요.

1. 1.

   기한 설정 후 작업 하나 생성

   생성 전에 전체 기한을 정하세요. 생성이 중단되었을 때 복구할 수 있도록 정확한 작업 입력과 함께 requestId를 보관하세요. 생성 중 기다리지 않으려면 대기 시간을 명시적으로 0으로 선택하세요.

2. 2.

   반환된 작업 ID 저장 및 상태 확인

   생성 시 이미 최종 결과가 반환될 수 있습니다. ready이면 솔루션을 반환하세요. failed이면 errorCode와 error를 확인하고 중단하세요. 실패한 해결 작업은 환불됩니다. pending과 solving일 때만 추가 폴링이 필요합니다.

3. 3.

   시간이 남아 있는 동안 같은 작업 조회

   GET /v1/tasks/:id를 사용하세요. 필요하면 최대 15000 ms의 롱 폴링 대기를 설정할 수 있습니다. 성공 페이로드를 읽기 전에 성공이 아닌 HTTP 응답을 처리하세요. 응답이 여전히 pending 또는 solving이면 다른 작업을 생성하지 말고 같은 ID로 반복하세요.

4. 4.

   기한에 도달하면 중단

   네트워크 오버헤드를 고려하여 각 요청의 제한 시간을 남은 시간 이내로 설정하세요. 기한이 만료되면 로컬 루프를 중단하고 복구를 위해 작업 ID를 보관하세요. 클라이언트가 대기를 중단했다는 이유만으로 작업을 실패로 취급하지 마세요.

이 요청은 서버 대기 시간 15초와 클라이언트 제한 시간 30초로 기존 작업을 조회합니다. TASK_ID를 저장한 ID로 설정하고 SOLVETHREE_API_KEY는 서버에 보관하세요. 어느 제한 시간도 반복 폴링 루프의 전체 기한은 아닙니다.

curl --fail-with-body --max-time 30 \
  "https://api.solvethree.com/v1/tasks/$TASK_ID?waitMs=15000" \
  -H "Authorization: Bearer $SOLVETHREE_API_KEY"

HTTP 성공 응답에도 추가 폴링이 필요한 작업이 포함될 수 있습니다. pending과 solving은 최종 상태가 아니며, ready에만 사용 가능한 솔루션이 포함됩니다. failed는 최종 상태이며 errorCode와 error를 포함합니다.

{
  "nonterminal": [
    {
      "id": "example-task",
      "status": "pending"
    },
    {
      "id": "example-task",
      "status": "solving"
    }
  ],
  "ready": {
    "id": "example-task",
    "status": "ready",
    "solution": {
      "token": "EXAMPLE_TOKEN",
      "userAgent": "EXAMPLE_USER_AGENT",
      "secChUa": "EXAMPLE_CLIENT_HINTS"
    }
  },
  "failed": {
    "id": "example-task",
    "status": "failed",
    "errorCode": "site-unreachable",
    "error": "target page did not respond"
  }
}

여기에 표시된 ready 응답에는 reCAPTCHA 토큰이 포함됩니다. 반면 Kasada는 헤더를 반환하고 TMPT는 원시 쿠키 값을 반환합니다. ready 결과는 솔루션이 생성되었다는 뜻이지, 후속 대상이 수락했다는 뜻은 아닙니다. 준비된 reCAPTCHA 토큰이 거부되면 폴링 진단 대신 제출한 토큰 확인으로 전환하세요.

연결 시간 초과는 클라이언트가 완전한 응답을 받지 못했다는 뜻입니다. 생성이 실패했다는 증거는 아닙니다. 다른 해결 작업에 비용을 지불하기 전에 이미 생성되었을 수 있는 작업을 복구하세요.

1. 1.

   작업 ID가 있으면 GET 폴링 재개

   유한한 로컬 기한을 새로 설정하여 해당 ID를 조회하세요. GET 시간 초과는 또 다른 생성 요청을 제출할 이유가 아닙니다.

2. 2.

   생성이 중단되었다면 해당 requestId 재사용

   같은 requestId로 동일한 작업 요청을 다시 전송하여 기존 작업을 복구하세요. 해당 ID를 재사용하면서 작업 입력을 변경하면 충돌이 발생합니다. 전체 규칙은 요청 ID를 통한 복구를 참조하세요.

두 SDK 모두 requestId가 생략되면 생성하며, 작업 생성을 자동으로 재시도하지 않습니다. SolvethreeError는 복구용 ID를 제공합니다. Python에서는 request_id와 task_id, JavaScript에서는 requestId와 taskId입니다. 새로운 논리적 작업을 생성하기로 결정하기 전에 이 필드를 확인하세요.

폴링 요청이 HTTP 오류를 반환함

작업 상태와 별도로 HTTP 상태를 확인하세요. SDK의 ApiError는 해당 상태와 재시도 대기 시간을 제공합니다.

다음을 시도해 보세요: 일시적인 폴링 실패에는 전체 해결 기한 내에서 Retry-After를 준수하세요. SDK 필드는 Python에서 초 단위의 retry_after, JavaScript에서 밀리초 단위의 retryAfterMs입니다.

작업이 failed를 반환함

errorCode와 error를 읽으세요. SDK는 이를 TaskFailedError로 나타냅니다.

다음을 시도해 보세요: 해당 작업의 폴링을 중단하세요. 다른 작업을 생성하기 전에 보고된 원인을 진단하세요. 잘못된 입력을 변경 없이 무작정 재시도하거나 크레딧 문제라고 단정하지 마세요.

조회가 HTTP 410을 반환함

저장된 결과가 만료되었습니다.

다음을 시도해 보세요: 일시적인 폴링 오류인 것처럼 조회를 계속 재시도하지 마세요. 완료된 결과의 보관 기간은 제한되어 있으며 영구적인 솔루션 캐시가 아닙니다.

ready 응답을 저장해도 대상의 토큰이나 쿠키 수명은 연장되지 않습니다.