---
title: Stripe API — Errors Reference
source_type: company-tech-blog
url: https://docs.stripe.com/api/errors
archive_url:
status: raw
confidence: high
tags: [ca-error-envelope, stripe, custom-envelope, rest-api, error-format, company-tech-blog]
related_projects: [ca-skeleton-operational-contract]
related_branches: [feature-operational-error-observability-foundation, feature-boundary-validation-mapping-contract, feature-business-rule-validation-contract]
created: 2026-05-22
last_reviewed: 2026-05-27
---

# 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 예시 (해석/구성):
  ```json
  {
    "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 표준 없음

## Related / 관련

- 같은 주제 다른 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: (미작성)