getTaskResult 결과 조회

getTaskResult는 비동기 작업의 결과를 조회해요. 작업을 만든 뒤 5초마다 호출하세요. processing이 반환되면 계속 기다리고, ready가 반환되면 결과는 solution에 들어 있어요. 오류가 반환되면 멈추세요. 조회는 포인트를 차감하지 않으니 몇 번을 조회해도 같아요.

POSThttps://api.yescaptcha.com/getTaskResult글로벌 엔드포인트복사

POSThttps://cn.yescaptcha.com/getTaskResult중국 엔드포인트복사

요청 파라미터

필드	타입	필수	설명
clientKey	string	예	계정 ClientKey예요. 작업을 만들 때 사용한 값과 같아야 해요
taskId	string	예	createTask가 반환한 작업 ID

{
  "clientKey": "YOUR_CLIENT_KEY",
  "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}

반환 결과

상황	반환	대응 방법
처리 중	errorId가 0, status가 processing	5초 뒤에 다시 조회하세요
완료	errorId가 0, status가 ready, 결과는 solution에 있음	solution을 가져오세요. 필드는 각 작업 유형 페이지에 있어요
인식 실패	errorId가 1, errorCode가 ERROR_CAPTCHA_UNSOLVABLE	포인트가 자동으로 환불됐어요. 작업을 다시 만들 수 있어요
시간 초과	errorId가 1, errorCode가 ERROR_TASK_TIMEOUT	포인트가 자동으로 환불됐어요. 작업을 다시 만들 수 있어요
작업이 없거나 만료됨	errorId가 1, errorCode가 ERROR_TASKID_INVALID	이 taskId의 조회를 멈추세요

완료됐을 때의 예시(reCAPTCHA v2):

{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "gRecaptchaResponse": "03AGdBq25SxXT-pmSeBXjzScW-EiocHwwpwqtk1QXlJnGnU..."
  }
}

규칙

• 5초마다 조회하세요. 같은 taskId를 5초 안에 다시 조회하면 바로 processing이 반환돼요. 더 자주 조회해도 빨라지지 않아요.
• 작업은 최대 약 110초 동안 처리돼요(일부 유형은 180~220초). 시간이 초과되면 ERROR_TASK_TIMEOUT이 반환되고 포인트가 자동으로 환불돼요. 코드의 대기 한도는 3분 정도로 설정하는 것을 권장해요.
• 결과는 약 10분 동안 보관돼요. 그 후에는 taskId가 만료되어 ERROR_TASKID_INVALID가 반환돼요. 결과를 받으면 가능한 한 빨리 사용하세요. 토큰 자체의 유효 기간은 더 짧아요(reCAPTCHA는 약 120초).
• 오류가 나면 멈추세요. errorId: 1이 반환된 뒤에 같은 taskId를 계속 조회해도 결과는 바뀌지 않아요. 이미 종료된 같은 작업을 3번째 조회하는 시점부터 errorDescription 끝에 폴링을 멈추라는 안내가 붙어요. ERROR_TASKID_INVALID는 자동 일시 중지의 오류 횟수에 포함돼요(같은 ID는 처음 한 번만 계산해요).
• 작업을 만든 엔드포인트에서 조회해야 해요.
• getTaskResult는 자동 일시 중지의 영향을 받지 않아요. 일시 중지되기 전에 만든 작업은 평소처럼 조회할 수 있어요.