donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
55de4f55b037af9554af9007ce834030ac7e729e
llm-wiki/raw/official-docs/idempotency-square-api.md
T

8.0 KiB
Raw Blame History

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

핵심 인용 / 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 / 관련

Reference in New Issue View Git Blame Copy Permalink