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
- Tasks — wait 헬퍼와 고급 task 폴링
- Authentication — 생성자 옵션과 signal
- API errors — 원시 HTTP에서의 동일한 코드
