중복 CAPTCHA 해결 없이 Python SDK 오류 처리하기

동기식 Python SDK의 solve 메서드는 작업을 한 번 생성하고 준비 완료 상태가 되거나 오류가 발생할 때까지 폴링합니다. 풀이 실패와 HTTP 요청 중단을 구분할 수 있도록 구체적인 예외를 SolvethreeError보다 먼저 포착하세요.

SOLVETHREE_API_KEY와 SOLVETHREE_PROXY를 설정한 다음, 예제 호스트 이름과 액션을 대상의 값으로 바꾸세요. 해당 사이트의 풀이를 진행하려면 먼저 활성 워크스페이스 프로필이 있어야 합니다.

import os
import uuid
from solvethree import Solvethree, ApiError, TaskFailedError, SolvethreeError

client = Solvethree(os.environ["SOLVETHREE_API_KEY"])
task = {"site": "accounts.example.com", "action": "login", "proxy": os.environ["SOLVETHREE_PROXY"], "requestId": str(uuid.uuid4())}
try:
    result = client.solve(task, timeout=180)
    print("Ready task:", result["id"])
    # Submit result["solution"] privately through the target application.
except TaskFailedError as error:
    print("Failed task:", error.task_id, "code:", error.error_code)
    # This task is terminal. Inspect it before starting different work.
except ApiError as error:
    print("HTTP status:", error.status, "retry delay:", error.retry_after)
    print("Recovery IDs:", error.request_id, error.task_id)
    # A known task_id means resume get_task; otherwise replay the exact task
    # with error.request_id. Do not generate a new logical request to recover it.
except SolvethreeError as error:
    print("Recovery IDs:", error.request_id, error.task_id)
    # Save these IDs and the original task inputs for explicit recovery.

• TaskFailedError: 작업이 최종 failed 상태에 도달했습니다. error.task_id와 error.error_code를 확인하고, 해당 작업의 폴링을 계속하지 마세요.
• ApiError: HTTP 요청이 실패했습니다. error.status와 초 단위인 error.retry_after를 확인하세요. 이는 작업의 최종 실패와는 다릅니다.
• SolvethreeError: 명시적인 복구를 위해 error.request_id와 error.task_id를 보관하세요. 생성이 전혀 이루어지지 않았다고 가정하지 말고, 사용 가능한 ID를 활용하세요.

이 예제는 복구 정보를 출력하지만 영구 저장하거나 복구를 수행하지는 않습니다. 프로세스 재시작 후에도 복구할 수 있어야 하는 연동에서는 solve를 호출하기 전에 원래 작업 입력과 요청 ID를 저장하고, 반환된 작업 ID도 보관하세요. 프록시 인증 정보가 포함된 저장 입력은 보호하세요.

1. 1.

   task_id가 있으면 get_task 재개하기

   solve를 다시 호출하지 말고 해당 작업을 조회하세요. get_task는 작업 ID와 wait_ms 인수를 받으며, 기본 대기 시간은 15000밀리초입니다. 상태가 pending 또는 solving인 동안 계속 조회하세요. 상태가 ready일 때만 솔루션을 사용하고, failed이면 중지하세요.

2. 2.

   작업 ID를 받기 전에 생성이 중단되었다면 create_task 재전송하기

   필요한 경우 복구한 request_id를 사용해 동일한 requestId로 동일한 작업 입력을 보내세요. 동일한 요청에 해당 ID를 재사용하면 기존 작업이 반환되며, 입력을 변경하면 충돌이 발생합니다. 작업 ID를 확보하면 get_task로 계속 진행하세요.

3. 3.

   복구 중에 다른 ID를 생성하지 마세요

   이 예제는 solve를 호출하기 전에 UUID를 생성합니다. 복구할 때 해당 값을 유지하세요. 작업 생성 코드를 다시 실행해 실수로 값을 바꾸지 마세요. 새 ID는 중단된 요청의 재시도가 아니라 별도의 요청을 나타냅니다.

SDK는 requestId를 생략하면 자동으로 생성하고, 오류에 복구 ID를 노출하며, 작업 생성을 자동으로 재시도하지 않습니다. solve 중 일시적인 폴링 실패가 발생하면 풀이 제한 시간 내에서 Retry-After를 따릅니다. 그래도 호출에서 예외가 발생하면 다른 풀이를 시작하지 말고 저장된 ID로 재개하세요.

ApiError가 발생하면 재전송 여부를 결정하기 전에 HTTP 오류를 확인하세요. 생성 결과가 불확실할 때는 중단된 생성을 복구하는 것이 적절하지만, 변경하지 않은 잘못된 입력을 무작정 다시 보내는 것은 적절하지 않습니다.

TaskFailedError가 발생하면 작업은 종료된 상태입니다. 조회한 실패 작업에는 errorCode와 error가 포함되며, Python 예외는 해당 코드를 error.error_code로 노출합니다. 이 정보를 바탕으로 무엇을 변경해야 할지 판단하세요. 예를 들어 site-unreachable이 발생하면 계정에 크레딧이 부족하다고 가정할 것이 아니라 대상에 연결할 수 있는지 조사해야 합니다. 실패한 풀이 비용은 환불됩니다.