Skip to main content
SDK는 두 가지 오류 클래스를 제공합니다: HTTP 및 검증 실패에는 YoukaRequestError, 비정상(성공이 아닌) 상태로 종료된 비동기 작업에는 YoukaTaskError를 사용합니다. 둘 다 Error를 확장하며, code, status, retryability로 분기할 수 있도록 구조화된 필드를 담고 있습니다.

YoukaRequestError

HTTP 오류, 요청 검증 실패, 그리고 잘못된 형식의 응답에 대해 발생합니다.

Fields

string
기계가 읽을 수 있는 오류 코드입니다. 예: INVALID_REQUEST, UNAUTHORIZED, UPLOAD_FAILED.
string
사람이 읽을 수 있는 설명입니다.
number
가능하다면 HTTP 상태 코드입니다.
boolean
SDK가 해당 오류를 재시도할 가치가 있다고 판단하면 true입니다(요청 제한, 일시적인 서버 오류, 멱등 재실행 진행 중).
unknown
서버가 제공한 상세 정보입니다. 일반적으로 검증 오류의 경우 Zod 이슈 목록입니다.

Common codes

YoukaTaskError

client.tasks.wait(...), client.projects.wait(...), client.exports.wait(...)에서, 기반이 되는 task 또는 export가 failed, cancelled, timed-out으로 종료되면 발생합니다.

Fields

'TASK_FAILED' | 'TASK_CANCELLED' | 'TASK_TIMED_OUT'
task의 종료 상태에 직접 매핑됩니다.
string
서버가 제공한 task 오류 메시지 또는 생성된 대체 메시지입니다.
TaskStatus
종료된 task 상태입니다.
RestTask
실패 시점의 전체 task 페이로드입니다. 로깅 및 사용자에게 보여줄 오류 메시지에 유용합니다.

Retry pattern

retryable을 멱등성 키와 함께 사용해 안전한 재시도 루프를 구성하세요:
재시도 전반에 걸쳐 항상 동일한 멱등성 키를 재사용하세요. 그렇지 않으면 서버가 재시도를 새로운 요청으로 처리하며, 중복이 생길 수 있습니다.

Abort and cancellation

요청을 중단(abort)하면 YoukaRequestError가 아니라 표준 AbortError가 발생합니다. 명시적으로 확인하세요:

What’s next