# 멱등성 — Idempotency-Key 헤더로 안전하게 재시도하기

> Idempotency-Key 헤더를 사용하여 문서 업로드, 배치 처리, bbox 트리거를 안전하게 재시도하세요. 동일한 작업이 두 번 실행되거나 비용이 이중으로 청구되지 않습니다.

네트워크 호출은 실패하고 타임아웃이 발생합니다. 크레딧을 소모하거나 리소스를 생성하는 요청에서 이러한 상황이 발생했을 때 단순히 재시도하면 크레딧이 두 번 사용될 수 있습니다. `Idempotency-Key` 헤더가 이 문제를 해결합니다. 재시도 시 동일한 키를 보내면 원래 호출과 완전히 동일한 응답을 반환받으며, 작업이 다시 실행되지 않습니다.

## 작동 방식

클라이언트에서 생성한 고유 문자열을 `Idempotency-Key` 헤더에 담아 지원되는 요청에 추가하세요.

```bash
curl -X POST https://imagetotable.ai/api/v1/batches/260716-4K9P/process \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3e9a2c-9b41-4e6a-8c3d-2f1a5b6c7d8e" \
  -d '{"fields": [{"name": "invoice_number"}, {"name": "total_amount"}]}'
```

키는 **24시간** 동안 ``별로 저장됩니다. 동일한 요청이 해당 시간 내에 다시 도착하면 원래 응답이 재생되며, 작업 자체는 두 번 실행되지 않습니다. 즉, 동일한 키로 재시도된 `process` 호출은 크레딧을 두 번 차감하지 않으며, 동일한 키로 재시도된 `documents` 업로드는 두 번째 문서를 생성하지 않습니다.

`Idempotency-Key` 헤더가 없는 요청은 이전과 동일하게 작동합니다. 아무것도 저장되지 않으며 재생되지 않습니다. 이 헤더는 전적으로 선택 사항입니다.

## 지원하는 엔드포인트

크레딧을 사용하거나 리소스를 생성하는 엔드포인트만 `Idempotency-Key`를 허용합니다. 읽기 전용 `GET` 요청에는 이점이 없습니다. 읽기 반복은 항상 안전하기 때문입니다:

- `POST /documents`
- `POST /batches/{batch_name}/process` (처리 시작, 크레딧 차감)
- `POST /documents/{document_id}/bbox` (유료 bbox 주석 단계 실행)

## 다른 매개변수로 키 재사용

`Idempotency-Key`는 범용 레이블이 아닌 *정확히 동일한* 요청을 재시도하기 위한 것입니다. 이미 사용한 키를 다른 요청 매개변수와 함께 재사용하면, API는 이전 응답을 자동으로 재생하지 않으며 어떤 요청을 의도했는지 추측하지 않습니다. 대신 400 `idempotency_key_reused` 오류를 반환합니다. 동일한 종류의 작업을 대상으로 하더라도 요청이 실제로 다른 경우에는 새 키를 생성하십시오.

## 예시: 재생된 응답

아래 두 번째 호출은 이미 성공한 호출과 동일한 키로 이루어졌으며, 첫 번째 호출과 동일한 본문과 상태 코드를 반환합니다. 크레딧이 다시 차감되지는 않습니다:

```json
{
  "batch_name": "260716-4K9P",
  "queued": 2,
  "quality": "fast",
  "webhook_registered": false
}
```

## 기록되는 내용

재생을 위해 저장되는 것은 성공(2xx) 응답뿐입니다. 원래 호출이 실패한 경우 아무것도 기록되지 않으며, 동일한 키로 재시도하면 작업을 새로 시도합니다. 이는 의도된 설계입니다. 오류가 발생한 상황에서는 키가 24시간 후 만료될 때까지 동일한 실패가 재생되는 것이 아니라, 재시도가 실제로 다시 시도되기를 원하기 때문입니다.

---

Source: https://imagetotable.ai/ko/developers/guides/idempotency