Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

10 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

Stripe API — Errors Reference

Layer: raw/company-tech-blogs/ — Stripe API Reference 의 Errors 페이지 verbatim. Stripe 는 결제 도메인의 사실상 reference 가 된 custom envelope 사례. company-tech-blog 자료 — 공식 표준이 아님. Stripe 의 vendor-specific API 컨벤션이며, 다른 REST 환경의 best practice 로 일반화 금지. ca-tmpl Topic 4 (Error Envelope) 의 대안 5 (Stripe custom envelope) 비교 근거.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-operational-error-observability-foundation	ca-tmpl Topic 4 (Error Envelope) 대안 비교 — Stripe 의 `type` / `code` / `param` / `doc_url` 1급 필드 vs ca-tmpl 의 `category`/`retryable` 비교 근거
raw/branch-notes/feature-boundary-validation-mapping-contract	boundary 입력 검증 실패 시 `param` 으로 form 필드 매핑 UX 패턴의 사례 근거 (industry case study, 표준 아님)
raw/branch-notes/feature-business-rule-validation-contract	business rule 실패의 `type` enum 4종 (card_error / api_error / idempotency_error / invalid_request_error) 분류 패턴 사례

컨텍스트 / 왜 저장했는지

Stripe 는 결제 도메인에서 가장 자주 인용되는 custom envelope 의 reference. ca-tmpl 이 custom 을 택했을 때 "유사한 1급 필드 구성" 을 어떻게 잡았는지 대조하기 위함. 단, 본 자료는 company tech blog/vendor reference 이므로 "공식 best practice" 가 아니라 "산업 사례" 로만 취급.

출처 / Source

원본 URL: https://docs.stripe.com/api/errors
아카이브 URL: (미수집)
저자 / 조직: Stripe Inc.
발행일: rolling docs (current Stripe API reference)
마지막 확인일: 2026-05-27

핵심 인용 / Key quotes (verbatim)

[§HTTP Status Code Summary] "Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with Stripe's servers (these are rare)."

[§Handling errors — Card errors] "Card errors are the most common type of error you should expect to handle. They result when the user enters a card that can't be charged for some reason."

[§Handling errors — Card errors] "For card errors, these messages can be shown to your users."

[§Error attributes — param] "If the error is parameter-specific, the parameter related to the error. For example, you can use this to display a message near the correct form field."

[§Error types] "api_error", "card_error", "idempotency_error", "invalid_request_error" — 4개 type enum (Stripe vendor 정의)

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
STRIPE-ERR-C1	Stripe API 는 HTTP status code 를 2xx success / 4xx caller error / 5xx Stripe server error 로 분류	[§HTTP Status Code Summary] "Codes in the `2xx` range indicate success. Codes in the `4xx` range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the `5xx` range indicate an error with Stripe's servers (these are rare)."	`company-case-study`	Stripe API 와 통신하는 client	HTTP RFC 의 일반적 표준이라는 뜻은 아님 — Stripe 의 자기 컨벤션 (RFC 7231/9110 의 일반 정의와 일치하지만 공식 표준 인용 아님)
STRIPE-ERR-C2	Stripe 에서 card errors 는 가장 흔한 error type 이며, user 가 청구 불가능한 카드를 입력했을 때 발생	[§Handling errors — Card errors] "Card errors are the most common type of error you should expect to handle. They result when the user enters a card that can't be charged for some reason."	`company-case-study`	Stripe 결제 통합 application 의 운영 빈도 가정	결제 도메인 일반의 통계라는 뜻은 아님 — Stripe 의 trafficcomposition 기반 안내
STRIPE-ERR-C3	card error 의 `message` 는 end-user 에게 직접 표시 가능 (다른 type 은 명시적 보장 없음)	[§Handling errors — Card errors] "For card errors, these messages can be shown to your users."	`company-case-study`	card_error type 메시지의 UX 표시 정책	api_error / idempotency_error / invalid_request_error 의 message 도 end-user 에 표시 가능하다는 뜻은 아님 — 본 인용은 card error 한정
STRIPE-ERR-C4	error 가 parameter-specific 인 경우, `param` 필드를 사용해 해당 form 필드 근처에 메시지를 표시 하도록 안내	[§Error attributes — param] "If the error is parameter-specific, the parameter related to the error. For example, you can use this to display a message near the correct form field."	`company-case-study`	Stripe Elements / 자체 form 통합 UX	RFC 7807 의 `instance` 또는 JSON:API 의 `source.pointer` 와 동일한 표준 개념이라는 뜻은 아님 — Stripe vendor-specific 평면 string
STRIPE-ERR-C5	Stripe error `type` 은 `api_error` / `card_error` / `idempotency_error` / `invalid_request_error` 의 4개 enum (vendor 정의) 으로 구성	[§Error types] "`api_error`", "`card_error`", "`idempotency_error`", "`invalid_request_error`"	`company-case-study`	Stripe API client 의 type-based 분기	다른 REST API 의 error category 가 동일한 4-종 분류를 따라야 한다는 best practice 가 아님 — Stripe vendor-specific

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것:
- STRIPE-ERR-C1: Stripe 의 HTTP status code 분류 정책 (Stripe 컨벤션)
- STRIPE-ERR-C2: card errors 가 Stripe 환경에서 가장 빈번
- STRIPE-ERR-C3: card error 메시지의 end-user 표시 가능성
- STRIPE-ERR-C4: param 의 form 필드 매핑 UX 패턴 사례
- STRIPE-ERR-C5: Stripe error type 4개 enum 의 존재
이 자료가 증명하지 않는 것:
- "Stripe 의 custom envelope 이 모든 REST API 의 best practice" — 본 자료는 company tech blog / vendor reference 로, 공식 표준이 아님. RFC 7807 / 9457, JSON:API, GraphQL spec 같은 official-standard 와 동일 권위로 다루면 안 됨
- retryable 명시 필드의 존재 (Stripe 응답에 1급 필드 없음 → 본 인용 범위에서 확인 안 됨, client 가 status + type 으로 추론)
- 성공 응답의 envelope 모양 (Stripe 는 envelope 없이 resource 직접 반환 → 별도 페이지)
- decline_code 의 완전한 값 카탈로그 (별도 페이지)
- i18n 정책 (Stripe API reference 본 페이지에 i18n 표준 없음)
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- ca-tmpl 이 Stripe 의 type 4-종 분류를 직접 채택할지, 자체 category 어휘를 정의할지
- doc_url 같은 error catalog URL 운영 비용 (RFC 7807 type URI 와의 의미적 차이 평가)
- SDK 의존 전략 (Stripe 처럼 envelope 을 자체 SDK 가 흡수하는 모델) 의 비용/이익
- 성공/실패 envelope 비대칭 (Stripe 모델) vs ca-tmpl 의 대칭 envelope 모델 trade-off

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

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

응답 shape 예시 (해석/구성):

{
  "error": {
    "type": "card_error",
    "code": "card_declined",
    "decline_code": "insufficient_funds",
    "message": "Your card has insufficient funds.",
    "param": "source",
    "doc_url": "https://stripe.com/docs/error-codes/card-declined",
    "charge": "ch_..."
  }
}

type enum: api_error / card_error / idempotency_error / invalid_request_error — ca-tmpl 의 category 와 거의 같은 의도
code 는 머신리더블, message 는 사람 대상
장점 (해석):
- type/code 분리 → category 기반 client 분기와 fine-grained handling 모두 가능
- doc_url 로 카탈로그 링크 (RFC 7807 의 type URI 와 유사 의도)
- param 이 form 필드와 직접 매핑 가능 → UX 친화적
단점 (해석):
- retryable 명시 필드 없음 — HTTP status 와 type 을 client 가 조합해서 추론해야 함
- 성공 응답은 envelope 없이 리소스를 그대로 반환 → 성공/실패 shape 비대칭
- 표준 미준수
ca-tmpl custom envelope 와의 차이 (해석):
- ca-tmpl 이 retryable 을 1급으로 가져간 점이 Stripe 보다 한 발 더 나감. 반대로 ca-tmpl 은 doc_url/param 이 1급은 아님 (있다면 details 안)
- Stripe 는 실패 envelope 만, ca-tmpl 은 성공·실패 모두 envelope
표준 준수 / lock-in / client 호환성 (해석):
- 표준 미준수. 그러나 Stripe SDK 가 envelope 을 흡수 → client 는 SDK 없이 직접 다룰 일이 적음. ca-tmpl 도 같은 전략 (자체 client 컨벤션) 이라면 합리적
localization / i18n 지원 여부 (해석):
- Stripe 는 message 를 영문 위주, decline_code 로 localize 는 client 가. 별도 i18n 표준 없음

같은 주제 다른 official-doc / company-tech-blog:
- raw/official-docs/spring-problem-detail (대안 1 구현체 — RFC 7807/9457 official-vendor-doc)
- raw/official-docs/google-api-error-format (대안 2 — gRPC google.rpc.Status official-vendor-doc)
- raw/official-docs/json-api-errors-spec (대안 3 — JSON:API errors official-standard)
- raw/official-docs/graphql-errors-spec (대안 4 — GraphQL errors official-standard)
canonical contract 섹션:
- raw/project-notes/ca-skeleton-operational-contract §3 Structured API Response Contract, §6 Operational Error Category
본 source 의 위치: ca-tmpl Topic 4 — Error Envelope, 대안 5: Stripe custom envelope (industry case study, 표준 아님)
인용하는 wiki: (미작성)

10 KiB Raw Blame History