---
title: Square API — Idempotency (Common API patterns)
source_type: official-doc
url: https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency
archive_url:
status: raw
confidence: high
tags: [ca-idempotency, square, payment-domain, body-mismatch-error, official-doc]
related_projects: [ca-skeleton-operational-contract]
related_branches: [feature-rate-limit-idempotency-contract, feature-api-contract-baseline]
created: 2026-05-22
last_reviewed: 2026-05-27
---

# Square API — Idempotency

> Layer: `raw/official-docs/` — Square Developer 공식 "Common API patterns" 페이지 발췌. ca-tmpl Topic 5 의 "body fingerprint mismatch → 명시적 error" 정책의 동일 사상 사례.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-rate-limit-idempotency-contract]] | "다른 body 면 error" 정책 (ca-tmpl 422) 의 결제 도메인 공식 사례 — Stripe 와 함께 body fingerprint mismatch 처리의 표준 패턴 근거 |
| [[raw/branch-notes/feature-api-contract-baseline]] | API contract baseline 에서 header vs body 필드 위치 선택의 trade-off (Square 는 body, Stripe/IETF draft 는 header) |

## 컨텍스트 / 왜 저장했는지

Square는 `idempotency_key`를 **header가 아닌 body 필드**로 받는 드문 케이스. fingerprint 처리도 "다른 body면 error"로 명시. ca-tmpl의 422 정책과 가장 가까운 도메인 사례.

## 출처 / Source

- 원본 URL: https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency
- 아카이브 URL: (미수집)
- 저자 / 조직: Square Developer (Block, Inc.)
- 발행일: rolling docs
- 마지막 확인일: 2026-05-27
- 보조: Square blog "Understanding the Essentials: Idempotency"
- 보조: Square API reference (`POST /v2/payments`, `POST /v2/payments/cancel`)

## 핵심 인용 / Key quotes (verbatim)

> [§What is idempotency?] "Square supports idempotency by allowing API operations to provide an idempotency key (a unique string)..."

> [§What is idempotency?] "If you use the same idempotency key but change the `CreatePayment` request (for example, specify a different payment amount), you get an error indicating that you used the idempotency key previously."

> [§What is idempotency?] "...the endpoint returns the response as the first successful `CreatePayment` response."

> [§What is idempotency?] "Idempotency keys can be anything, but they need to be unique."

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| IDMP-SQ-C1 | Square 의 idempotency 는 API operation 이 unique string 인 idempotency key 를 제공하는 방식으로 지원됨 | [§What is idempotency?] "Square supports idempotency by allowing API operations to provide an idempotency key (a unique string)..." | `official-vendor-doc` | Square API operations 중 idempotency_key 를 지원하는 endpoint | 모든 Square endpoint 가 idempotency_key 를 지원한다는 뜻은 아님 — 명시된 endpoint (CreatePayment 등) 한정 |
| IDMP-SQ-C2 | 같은 idempotency key 로 다른 request (예: payment amount 변경) 를 보내면 "이미 사용한 키" 라는 error 응답 — body fingerprint mismatch 시 명시적 거부 | [§What is idempotency?] "If you use the same idempotency key but change the `CreatePayment` request (for example, specify a different payment amount), you get an error indicating that you used the idempotency key previously." | `official-vendor-doc` | CreatePayment 및 유사 endpoint | 정확한 HTTP status code (409 / 422 / 400) 는 본 인용에 명시되지 않음 — Square API reference 별도 확인 필요. "Note that this behavior might vary depending on the API." (Square 본문 caveat) |
| IDMP-SQ-C3 | 완료된 같은 idempotency key 의 replay → 첫 성공 응답을 그대로 반환 | [§What is idempotency?] "...the endpoint returns the response as the first successful `CreatePayment` response." | `official-vendor-doc` | 동일 key + 동일 body 의 retry | TTL (replay 가능 기간) 은 본 인용에 명시되지 않음 — Square 문서의 알려진 갭 |
| IDMP-SQ-C4 | idempotency key 의 값은 임의의 string 이지만 unique 해야 함 | [§What is idempotency?] "Idempotency keys can be anything, but they need to be unique." | `official-vendor-doc` | 클라이언트의 key 생성 정책 | "unique" 의 scope (글로벌 / merchant 단위 / endpoint 단위) 가 무엇인지 본 인용에서는 불명확 — 별도 endpoint 문서 확인 필요 |

## Usage Boundaries / 적용 경계

- **이 자료가 직접 증명하는 것**:
  - `IDMP-SQ-C1`: Square 의 idempotency 지원 방식 (client-supplied unique key)
  - `IDMP-SQ-C2`: body fingerprint mismatch 시 명시적 error (ca-tmpl 422 정책의 동일 사상)
  - `IDMP-SQ-C3`: 완료된 키의 first response replay
  - `IDMP-SQ-C4`: key uniqueness 요구
- **이 자료가 증명하지 않는 것**:
  - idempotency key 의 정확한 위치 (header vs body 필드) — 본 발췌에는 명시 없음, Square API reference 의 endpoint 별 schema 에서 `idempotency_key` 가 request body 필드로 정의되어 있음을 별도 확인 필요
  - TTL / 보존 기간 — Square 문서의 알려진 갭
  - in-flight (동일 key 의 동시 호출) 처리 방식 — 본 인용에 명시 없음
  - mismatch error 의 정확한 HTTP status code
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
  - ca-tmpl 이 422 를 채택할 때 Square 의 error code 를 1:1 대응시킬 수 있는지 (Square 의 정확한 code 확인 후 본문 매핑)
  - header vs body 필드 선택의 trade-off (미들웨어 dedup 가능성 vs API contract 단순성)

## 메모 / Notes (내 프로젝트 해석)

> 본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.

- **key scope (어떤 dimension으로):** body 필드로 받고 endpoint별로 처리 → `(merchant_account, endpoint, idempotency_key)`. ca-tmpl triple과 거의 동일 구조.
- **TTL:** 문서에 명시 안됨 (Square의 단점 중 하나로 자주 지적됨).
- **저장소:** 미공개.
- **duplicate 처리:**
  - 완료된 동일 key + **동일 request** → first response 반환.
  - 완료된 동일 key + **다른 request** → error.
- **fingerprint (same key, different body):** **명시적으로 error 반환**. ca-tmpl 422 정책과 같은 사상.
- **in-flight:** 문서 명시 없음.
- **장점:**
  - body fingerprint 정책이 명시적이라 클라이언트 버그 조기 발견.
  - `cancel-payment-by-idempotency-key`처럼 키 자체를 resource handle로 쓰는 API 디자인 가능 (Stripe·PayPal엔 없음).
- **단점:**
  - body 필드 방식 → 헤더 표준(IETF draft, Stripe, PayPal)과 호환 안 됨. 미들웨어 레벨에서 dedup 어려움.
  - TTL 미공개 → 클라이언트가 retry 윈도우를 못 가늠.
  - in-flight 동작 미정의.
- **ca-tmpl과의 차이:**
  - ca-tmpl은 header 기반 (IETF 표준 준수), Square는 body 필드 → ca-tmpl이 더 표준에 가까움.
  - fingerprint mismatch error: 두 시스템 모두 동일 사상. ca-tmpl이 422라는 status code까지 명시한 게 한 단계 더 엄격.
  - scope: 사실상 동급 (양쪽 다 account + endpoint + key).
  - in-flight: Square 미정의 vs ca-tmpl 200ms wait → ca-tmpl이 명시적·예측 가능.

## Related / 관련

- 같은 주제 다른 official-doc:
  - [[raw/official-docs/idempotency-aws-lambda-powertools]] — server-derived key 모델
  - [[raw/official-docs/idempotency-no-api-level-github-rest]] — server dedup 부재 모델
- canonical contract 섹션:
  - [[raw/project-notes/ca-skeleton-operational-contract]] §13. API Contract Surface (Idempotency-Key)
  - [[raw/project-notes/ca-skeleton-operational-contract]] §18. Control Plane Contract (Rate Limit/Idempotency)
- 대안 그룹: **Topic 5 — Idempotency** (대안 5종 + 보조 1종: triple scope / Stripe pair / URL-based / content-hash / no-dedup / + DB vs Redis 저장소)
- 본 source의 위치: **대안 4: Square endpoint-scoped**