donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
58515ab0f3c9b94ed48e9efe7a11bb52c169ce83
llm-wiki/raw/official-docs/idempotency-paypal-docs.md
T

11 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
PayPal REST API — Idempotency (PayPal-Request-Id) official-doc https://developer.paypal.com/api/rest/reference/idempotency/ raw medium
ca-idempotency
paypal
pair-scope
payment-domain
ca-skeleton-operational-contract
feature-rate-limit-idempotency-contract
feature-api-contract-baseline
2026-05-22 2026-05-27

PayPal REST API — Idempotency (PayPal-Request-Id)

Layer: raw/official-docs/ — PayPal 공식 REST API 의 idempotency header (PayPal-Request-Id) 정의. Stripe Idempotency-Key 와 다른 헤더명, 다른 TTL 정책의 비교 reference.

Parent / 활용 branch (필수)

Branch 이 자료가 정당화하는 결정
raw/branch-notes/feature-rate-limit-idempotency-contract (request_id, API call type) pair scope + 45일 TTL + in-flight "might fail" 모델의 비교 근거
raw/branch-notes/feature-api-contract-baseline 헤더명 차이 (vendor 마다 Idempotency-Key vs PayPal-Request-Id 등) 가 API surface 표준화 결정에 미치는 영향
raw/project-notes/ca-skeleton-operational-contract §13. API Contract Surface (Idempotency-Key) + §18. Control Plane Contract — 가장 긴 TTL 사례 reference

컨텍스트

PayPal 의 PayPal-Request-Id 는 Stripe Idempotency-Key 와 다른 헤더명을 쓰지만 동일 개념. scope 를 "request × API call type" 으로 정의한다는 명시가 있어 ca-tmpl triple 과의 비교에 유리. 또한 결제 도메인에서 가장 긴 TTL (45일) 사례.

출처 / Source

  • 원본 URL: https://developer.paypal.com/api/rest/reference/idempotency/
  • 보조 URL: https://developer.paypal.com/api/rest/requests/ (API 요청 가이드)
  • 아카이브 URL: (미수집)
  • 저자 / 조직: PayPal Holdings, Inc. — Developer Documentation
  • 발행일: rolling docs
  • 마지막 확인일: 2026-05-27 (WebFetch 성공 — C2, C4, C5 는 verbatim 재확인 완료 → official-vendor-doc upgrade. C1 은 fragment 일치 + 후반부 ("to enforce idempotency on REST API POST calls") 미확인. C3 (45일 TTL) 은 페이지 개정으로 NOT FOUND — 현재 페이지는 "for a period of time" 만 언급, 45-day 수치 없음 → 계속 needs-confirmation)

핵심 인용 / Key quotes (verbatim)

[§Idempotency, 2026-05-22 capture, 2026-05-27 partial verified — "unique user-generated ID that the server stores for a period of time" fragment 일치, 후반부 ("to enforce idempotency on REST API POST calls") 는 WebFetch 응답에 미포함] "The PayPal-Request-Id request header contains a unique user-generated ID that the server stores for a period of time to enforce idempotency on REST API POST calls."

[§Idempotency, 2026-05-22 capture, 2026-05-27 verified verbatim] "The PayPal-Request-Id header value must be unique for both each request and an API call type. For example, authorize payment and capture authorized payment."

needs-confirmation [§Idempotency, 2026-05-22 capture, 2026-05-27 NOT FOUND — 현재 페이지는 "for a period of time" 만 언급, 45-day 수치 없음] "PayPal stores your unique ID for up to 45 days. If you retry a call with the same PayPal-Request-Id, PayPal recognizes it as a duplicate and returns the result of the original call."

[§Idempotency, 2026-05-22 capture, 2026-05-27 verified verbatim] "When you send two simultaneous API requests with same PayPal-Request-Id header, PayPal processes the first request and might fail the second request."

[§Idempotency, 2026-05-22 capture, 2026-05-27 verified verbatim] "You can retry idempotent calls that fail with network timeouts or HTTP 5xx status codes for as long as the server stores the ID."

2026-05-27 재검증 결과: C2, C4, C5 verbatim 확인 (official-vendor-doc upgrade). C1 은 partial (fragment 일치). C3 (45일 TTL) 은 NOT FOUND — PayPal 이 페이지를 개정하여 구체 일수를 제거했을 가능성 (현재는 "for a period of time" 만 명시). ca-tmpl 24h TTL vs PayPal 45일 비교 분석을 사용하는 모든 downstream 문서는 PayPal 의 명시적 45-day 수치 출처를 다른 페이지/archive snapshot 으로 보강 필요.

Claims Extracted / 추출된 주장

Claim ID Claim (이 자료가 직접 말하는 것) Evidence quote Strength Applies to Does not prove
PAYPAL-IDEMP-C1 PayPal-Request-Id 는 client 가 생성한 unique ID 를 server 가 일정 기간 저장하여 REST API POST 호출의 idempotency 를 강제 [§Idempotency, 2026-05-22 capture, 2026-05-27 partial verified — fragment 일치] "The PayPal-Request-Id request header contains a unique user-generated ID that the server stores for a period of time to enforce idempotency on REST API POST calls." needs-confirmation (partial — fragment "unique user-generated ID that the server stores for a period of time" 만 verbatim 확인, 후반부 미확인) PayPal REST API POST endpoint Stripe Idempotency-Key 와 100% 동일 동작이라는 뜻은 아님
PAYPAL-IDEMP-C2 unique 성은 (request, API call type) 두 축 모두에 대해 요구 — authorize payment 과 capture authorized payment 가 별도 idempotency 단위 [§Idempotency, 2026-05-22 capture, 2026-05-27 verified verbatim] "The PayPal-Request-Id header value must be unique for both each request and an API call type. For example, authorize payment and capture authorized payment." official-vendor-doc PayPal REST API 의 endpoint 간 분리 가맹점 (account) dimension 의 명시적 분리는 본 인용에 없음 — API 키 인증으로 implicit
PAYPAL-IDEMP-C3 PayPal 은 unique ID 를 최대 45일까지 저장하며, 동일 ID 로 재시도 시 duplicate 으로 인식하여 original call 의 결과를 반환 [§Idempotency, 2026-05-22 capture, 2026-05-27 NOT FOUND — 현재 페이지는 "for a period of time" 만 언급] "PayPal stores your unique ID for up to 45 days. If you retry a call with the same PayPal-Request-Id, PayPal recognizes it as a duplicate and returns the result of the original call." needs-confirmation PayPal idempotency store 45일 수치 자체가 현재 페이지에 부재 — 페이지 개정 가능성, 다른 출처 보강 필요
PAYPAL-IDEMP-C4 동일 PayPal-Request-Id 로 두 simultaneous request 를 보내면 PayPal 은 first 를 처리하고 second 는 fail 시킬 수 있다 ("might fail") [§Idempotency, 2026-05-22 capture, 2026-05-27 verified verbatim] "When you send two simultaneous API requests with same PayPal-Request-Id header, PayPal processes the first request and might fail the second request." official-vendor-doc PayPal 의 in-flight 동시 요청 처리 "might fail" 의 정확한 status code / error 형태는 본 인용에 없음. 항상 fail 한다는 뜻도 아님 (확률적 표현)
PAYPAL-IDEMP-C5 network timeout 또는 5xx 로 실패한 idempotent call 은 server 가 ID 를 저장하는 기간 동안 재시도 가능 [§Idempotency, 2026-05-22 capture, 2026-05-27 verified verbatim] "You can retry idempotent calls that fail with network timeouts or HTTP 5xx status codes for as long as the server stores the ID." official-vendor-doc retry 정책 설계 4xx 실패에 대한 재시도 권장 여부는 본 인용 범위 밖
PAYPAL-IDEMP-C6 same key + different body (fingerprint mismatch) 의 처리 정책은 본 인용 범위 내에 명시 없음 (부재 자체가 claim) needs-confirmation body fingerprint mismatch 처리 PayPal 이 body diff 를 무시한다는 뜻도, 거부한다는 뜻도 아님. 문서가 직접 다루지 않음

Usage Boundaries / 적용 경계

  • 이 자료가 직접 증명하는 것:
    • 2026-05-27 verbatim 확인 완료 (official-vendor-doc): C2 (request × API call type scope), C4 (simultaneous "might fail"), C5 (5xx/timeout retry 허용)
    • 2026-05-27 partial (fragment 일치): C1 (header 의 unique user-generated ID 저장 메커니즘)
    • 2026-05-27 NOT FOUND: C3 (45일 TTL — 현재 페이지는 "for a period of time" 만 명시)
  • 이 자료가 증명하지 않는 것:
    • PAYPAL-IDEMP-C6: same-key + different-body 시 동작 (body fingerprint 정책)
    • 가맹점 dimension 의 명시적 분리 (인증으로 implicit 으로 추정)
    • "might fail" 의 정확한 status code / 재시도 권장 backoff
    • 저장소 backend (외부 관찰 불가)
  • 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
    • 2026-05-27 시점 페이지 재확인 (WebFetch 차단으로 본 migration 에서 미실행)
    • ca-tmpl 의 (principal, key, useCaseName) triple 과 PayPal (request_id, API call type) pair 의 mapping (PayPal 은 가맹점 implicit)
    • ca-tmpl 24h TTL 결정의 위험 (PayPal 45일 대비 매우 짧음 — 결제 분쟁 윈도우 손실 vs 저장 비용)
    • ca-tmpl 200ms wait 동작이 PayPal "might fail" 보다 클라이언트 친화적이라는 해석의 정합성

ca-tmpl 함의 (내 프로젝트 해석)

본 섹션은 자료 직접 인용이 아닌 ca-tmpl 결정 컨텍스트 해석. wiki 추출 시 source-summary 로 옮겨야 함.

  • key scope: PayPal (request_id, API call type) ≈ ca-tmpl (key, useCaseName). principal dimension 은 PayPal 에선 인증으로 implicit, ca-tmpl 은 explicit triple 로 박아둠 → ca-tmpl 이 멀티테넌시에서 더 명시적이고 안전.
  • TTL: PayPal 45일 ≫ ca-tmpl 24h. ca-tmpl 이 훨씬 보수적 (저장 부하 낮음, retry 윈도우 짧음).
  • in-flight: PayPal "might fail" (C4) vs ca-tmpl 200ms wait → ca-tmpl 이 결정적·사용자 친화적 (단, 표준 동작은 아님 — IETF draft 는 409 즉시 권장).
  • fingerprint: PayPal 미명시 (C6) vs ca-tmpl 422 명시 → ca-tmpl 이 더 엄격.

메모 / Notes

  • 2026-05-27 재검증 완료: WebFetch 성공. C2/C4/C5 verbatim 일치 → official-vendor-doc upgrade. C1 partial. C3 (45일 TTL) NOT FOUND — PayPal 이 페이지에서 구체 일수를 제거했을 가능성 (현재는 "for a period of time" 만 명시).
  • ca-tmpl 24h TTL vs PayPal 45일 비교 분석을 사용하는 모든 downstream claim 은 PayPal 의 45-day 출처를 다른 페이지/archive snapshot/changelog 으로 보강 필요. C3 인용을 그대로 외부 산출물에 사용 금지.

Related / 관련

Reference in New Issue View Git Blame Copy Permalink