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

> ## Agent Instructions
> Treat these docs and the Whop MCP server as the source of truth for Whop API behavior. Don't infer endpoint behavior from marketing pages.
> MCP server: connect https://mcp.whop.com/mcp (streamable HTTP, browser sign-in, no API key in the client config) to search these docs and read or change live Whop data. Setup: https://docs.whop.com/developer/guides/ai_and_mcp.md
> Whop CLI: install with `curl -fsSL https://whop.com/install.sh | sh` to scaffold, run, and deploy Whop apps and websites. It acts on production, not the sandbox. Overview: https://docs.whop.com/cli/overview.md Agent mode: https://docs.whop.com/cli/agent-mode.md
> Hosting: Whop serves a site or app from the build `whop apps deploy` uploads, with rollbacks, secrets, and server logs. Guide: https://docs.whop.com/developer/websites/hosting.md
> Plugins: in Claude Code, run `/plugin marketplace add whopio/plugins`, then `/plugin install whop@whop`. Guide: https://docs.whop.com/developer/guides/plugins/claude-code.md Every agent tool: https://docs.whop.com/developer/ai/overview.md
> Environments: build and test in the sandbox (API `https://sandbox-api.whop.com/api/v1`, keys at https://sandbox.whop.com/dashboard/developer, SDK environment `Sandbox`; no real money). Production (API `https://api.whop.com/api/v1`, keys at https://whop.com/dashboard/developer, SDK environment `Production`, the SDK default) moves real money, so use it only at launch. The two share no accounts, keys, products, or webhooks, and their keys look identical: never mix them. Sandbox guide: https://docs.whop.com/developer/guides/sandbox.md Comparison: https://docs.whop.com/developer/quickstart.md
> API: send `Authorization: Bearer <API_KEY>` from your server only, and pin a dated version with the `Api-Version-Date` header. OpenAPI spec: https://api.whop.com/api/v1/openapi.json
> Which API: build on the Current API, whose pages live under https://docs.whop.com/api-reference/ (start at https://docs.whop.com/api-reference/overview.md). Pages under /api-reference/legacy/ are the Legacy API. Use one only when https://docs.whop.com/api-reference/stability.md lists the resource as Legacy-only.

# 멱등성 요청

> 멱등성 키로 POST 요청을 재시도하여 요청이 두 번 실행되지 않도록 하세요.

Current API의 모든 인증된 `POST`는 `Idempotency-Key` 헤더를 받습니다. 키가 포함된 요청이 성공하면 응답이 24시간 동안 저장됩니다. 같은 키로 재시도하면 요청을 다시 실행하는 대신 저장된 응답을 재생합니다. 따라서 시간 초과되거나 내 쪽에서 오류가 발생한 요청을 중복 청구, 이체, 리소스 생성의 위험 없이 안전하게 재시도할 수 있습니다.

최대 255바이트의 고유한 문자열이면 무엇이든 키로 사용할 수 있으며, UUID가 좋은 기본값입니다. 서로 다른 작업마다 새 키를 생성하고, 해당 작업을 재시도할 때만 정확히 같은 키를 재사용하세요.

```bash theme={null}
curl -X POST https://api.whop.com/api/v1/transfers \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Idempotency-Key: d9105228-4a08-46b1-8b91-42fed586d383" \
  -H "Content-Type: application/json" \
  -d '{"type": "balance", "amount": "10.00", "currency": "usd", "destination_id": "user_XXXXXXXX"}'
```

| 재시도 방식 | 결과 |
| - | - |
| 같은 키, 같은 요청 | 원래 응답이 재생됨 — 두 번째 실행이 아님 |
| 같은 키, 다른 요청 | `400` 오류 |
| 같은 키, 첫 번째 요청이 아직 실행 중일 때 | `409` 오류 — 첫 번째 요청이 끝난 후 재시도하세요 |
| 같은 키, 24시간 이후 | 키가 새것인 것처럼 새로 실행됨 |

재생된 응답은 상태 코드를 포함하여 원래 응답과 바이트 단위로 동일하며, `Idempotent-Replayed: true` 헤더가 포함되어 재생과 새 실행을 구분할 수 있습니다.

> [!NOTE]
>
> **오류 응답도 재생됩니다.** 원래 요청이 `4xx`로 실패했다면 같은 키로 재시도해도 동일한 오류가 반환됩니다. 그 실패가 요청의 실제 결과이므로, 대신 수정된 요청과 함께 새 키를 보내세요.

알아두면 좋은 몇 가지 세부 사항:

* "같은 요청"이란 메서드, 경로, 쿼리 문자열, 본문, `Api-Version-Date`가 모두 원래 요청과 정확히 일치하는 것을 의미합니다. 차이가 있으면 키 재사용으로 간주되어 `error.code`가 `idempotency_key_mismatch`인 `400`으로 거부됩니다.
* 키의 범위는 인증된 호출자로 한정됩니다. 서로 다른 두 API 키나 사용자는 충돌 없이 같은 키 값을 사용할 수 있습니다.
* 인증되지 않은 요청과 `POST`가 아닌 메서드에서는 헤더가 무시됩니다. `GET`, `PATCH`, `DELETE` 요청은 안전하게 재시도할 수 있습니다.
* 키가 포함된 첫 번째 요청이 아직 실행 중일 때 재시도하면 `error.code`가 `idempotency_request_in_progress`인 `409`가 반환됩니다. 첫 번째 요청이 알 수 없는 결과로 실패한 경우(예: 요청 도중 서버 충돌), 키가 만료될 때까지 재시도는 계속 해당 `409`를 반환합니다. API는 요청을 두 번 실행할 위험을 절대 감수하지 않습니다.


## Related topics

- [AI 및 MCP](https://docs.whop.com/ko/developer/guides/ai_and_mcp.md)
- [API 버전](https://docs.whop.com/ko/developer/api/versioning.md)
- [Cashback Rules API](https://docs.whop.com/ko/api-reference/cashback-rules/cashback-rule.md)
