solvethree API 오류: 수정할 사항과 재시도 시점

성공 페이로드를 읽기 전에 성공이 아닌 HTTP 응답을 처리하세요. POST /v1/tasks에서 201은 새 작업이 생성되었음을, 200은 멱등 재전송으로 기존 작업이 반환되었음을 뜻합니다. 어느 응답도 풀이가 완료되었음을 뜻하지는 않습니다.

400 — 잘못된 요청 본문

제출한 본문을 해당 작업 유형에 대해 문서에 명시된 필드 및 요구 사항과 비교하세요.

다음을 시도해 보세요: 다시 제출하기 전에 입력을 수정하세요. 잘못된 본문을 변경 없이 재시도해도 해결되지 않습니다. 작업 생성 명세를 사용해 요청을 확인하세요.

401 — 유효하지 않은 API 키

요청에 Authorization: Bearer와 그 뒤에 유효한 워크스페이스 API 키가 포함되어 있는지 확인하세요.

다음을 시도해 보세요: 누락된 키를 추가하거나 거부된 키를 수정하세요. 브라우저 코드에 노출하지 말고 서버에 보관하세요.

402 — 크레딧 부족

API 키에 연결된 워크스페이스의 크레딧 잔액을 확인하세요.

다음을 시도해 보세요: 재시도하기 전에 해당 워크스페이스에 크레딧을 충전하세요. 관련 없는 HTTP 오류나 작업 실패를 잔액 문제로 간주하지 마세요.

403 — 비활성 사이트 프로필

reCAPTCHA의 경우 대상 사이트에 워크스페이스에서 사용할 수 있는 활성 프로필이 있는지 확인하세요.

다음을 시도해 보세요: 콘솔에서 대상 사이트를 설정하고 프로필이 활성 상태인지 확인하세요. 작업에 호스트 이름과 액션을 지정해도 프로필이 생성되지는 않습니다. 이 게이트웨이 응답은 대상 웹사이트가 요청을 차단했다는 증거가 아닙니다.

409 — 요청 ID 충돌

동일한 requestId가 이전에 다른 작업 입력에 사용되었는지 확인하세요.

다음을 시도해 보세요: 원래 입력을 사용해 원래 작업을 복구하세요. 다른 작업을 생성하려는 경우 새 요청 ID를 부여하세요.

410 — 저장된 결과 만료

저장된 결과가 더 이상 보존되지 않는 완료된 작업을 조회하고 있는지 확인하세요.

다음을 시도해 보세요: 해당 결과 조회를 중단하세요. 풀이가 여전히 필요하면 새로 생성하세요. 이 상태는 API 결과 보존에 관한 것이며, 대상 토큰이나 쿠키의 유효 기간을 나타내지 않습니다.

429 — 요청 속도 제한

실제 Retry-After 응답을 확인하세요.

다음을 시도해 보세요: 안내된 시간만큼 기다린 뒤 재시도하고 요청 속도를 줄이세요. 제한이 적용되는 동안 같은 속도로 폴링하거나 제출하지 마세요.

502 — 생성 서비스 이용 불가

서비스 이용 불가를 잘못된 입력이나 크레딧 부족과 구분하세요.

다음을 시도해 보세요: 나중에 재시도하세요. 동일한 생성 요청을 다시 시도할 때는 요청 ID와 변경하지 않은 작업 입력을 재사용하세요.

HTTP 503은 생성 처리 용량을 이용할 수 없다는 뜻입니다. 나중에 재시도하세요. 동일한 생성 요청에는 요청 ID와 변경하지 않은 작업 입력을 재사용하세요.

• pending 또는 solving: 기존 작업을 계속 폴링하세요. 아직 준비되지 않았다는 이유만으로 대체 작업을 생성하지 마세요.
• ready: 폴링을 중단하고 솔루션을 읽으세요.
• failed: 폴링을 중단하고 errorCode와 error를 확인하세요.

{
  "id": "example_login_001",
  "status": "failed",
  "errorCode": "site-unreachable",
  "error": "target page did not respond"
}

여기서 site-unreachable은 HTTP 상태가 아니라 작업 오류 코드입니다. 다른 풀이를 요청하기 전에 제출한 대상 URL과 페이지의 응답 여부를 확인하세요. 추가로 폴링해도 이 실패한 작업은 다시 시작되지 않으며, 원래 요청 ID로 재전송하면 대체 작업을 시작하는 대신 기존 작업이 반환됩니다.

연결 시간 초과만으로 작업 생성이 실패했다고 단정할 수는 없습니다. 동일한 논리적 작업을 안전하게 복구할 수 있도록 첫 생성 시도 전에 선택 항목인 requestId를 지정하세요. ASCII 영문자, 숫자, 밑줄 또는 하이픈으로 구성된 1–64자여야 합니다.

1. 1.

   작업 ID가 있으면 해당 작업 조회

   GET /v1/tasks/:id를 사용하고 작업 상태를 확인하기 전에 HTTP 응답을 처리하세요.

2. 2.

   생성 응답이 유실되면 원래 요청 재전송

   동일한 작업 입력을 동일한 요청 ID로 제출하세요. 작업이 생성되었다면 멱등 재전송으로 기존 작업이 반환됩니다. 해당 ID에 연결된 입력을 변경하지 마세요.

3. 3.

   다른 풀이를 시작하려는 경우에만 대체 작업 생성

   새 요청 ID는 이전 요청의 복구가 아니라 새 작업을 의미합니다. 예를 들어 최종 실패 원인을 조사한 후 다시 시도하기로 결정한 경우처럼, 명확한 의도를 가지고 사용하세요.

재전송 처리에 대해서는 요청 ID를 통한 복구를, 생성은 성공했지만 작업이 아직 실행 중인 경우에는 폴링 및 시간 초과를 참고하세요.