> ## Documentation Index
> Fetch the complete documentation index at: https://docs.youka.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 오류 및 재시도 동작

> 오류 페이로드 형태, 안전한 재시도 가이드, 그리고 재시도를 멱등성 키와 함께 사용하는 방법.

# 오류 및 재시도 동작

성공이 아닌 응답은 다음과 같은 엔벨로프를 사용합니다:

```json theme={null}
{
  "error": {
    "code": "SOME_CODE",
    "message": "Human-readable explanation",
    "issues": []
  }
}
```

## 재시도 가이드

* 전송(transport) 실패는 재시도하세요.
* 멱등성 있는 쓰기 작업은 동일한 `Idempotency-Key`로 재시도하세요.
* 첫 번째 응답이 완료되었다고 가정하지 말고, 비동기 작업 이후에는 내구 상태(durable state)를 다시 읽으세요.

## 실용 규칙

* 서버 측 실패는 원래의 쓰기 작업이 안정적인 멱등성 키를 사용한 경우에만 재시도 대상으로 취급하세요.
* 새로운 export 다운로드 URL은 임시로 취급하고, 필요할 때 `GET /exports/{exportId}`에서 다시 읽어오세요.
* 변경 작업(mutation)이 이미 진행 중이거나 현재 상태와 충돌하는 경우, 반환된 `code`를 확인하고 작업이 논리적으로 여전히 안전할 때만 재시도하세요.

## 기계 판독형 클라이언트

제공되는 Node.js SDK와 CLI는 오류를 다음을 포함한 구조화된 객체로 정규화합니다:

* `code`
* `message`
* `status`
* `retryable`

이를 통해 자유 형식 문자열을 파싱하지 않고도 자동화 로직을 안전하게 분기할 수 있습니다.