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

토스페이먼츠 API Error Format

Layer: raw/company-tech-blogs/ — 토스페이먼츠 개발자센터 공식 API reference (docs.tosspayments.com). source_type 은 company-tech-blog 디렉토리이나 strength 는 official-vendor-doc. 자동 mv 금지 규칙으로 디렉토리 유지 — 후속 정리 권고. 검증된 요약은 /ingest 후 wiki/concepts/에 별도 작성.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-operational-error-observability-foundation	error envelope 의 한국 vendor 사례. ca-tmpl 의 두꺼운 envelope vs 토스의 얇은 `{code, message}` 비교 base
raw/branch-notes/feature-boundary-validation-mapping-contract	`INVALID_REQUIRED_PARAM` 등 validation 코드 명명 컨벤션의 한국 결제 vendor 사례
raw/branch-notes/feature-business-rule-validation-contract	business rule 위반 코드 (`ALREADY_PROCESSED_PAYMENT`, `NOT_CANCELABLE_PAYMENT`) 의 도메인-specific 어휘 사례
raw/project-notes/ca-skeleton-operational-contract	§3. Structured API Response Contract + §6. Operational Error Category 의 한국 reference

컨텍스트

한국 결제/금융 도메인의 대표 사례. ca-tmpl 의 한국어 메시지·운영 컨벤션과 비교 가능. Stripe / GitHub 대비 더 얇은 envelope 이 한국 사용자/개발자에게 어떻게 자리 잡았는지 관찰.

출처 / Source

원본 URL: https://docs.tosspayments.com/reference/error-codes
보조: https://docs.tosspayments.com/reference/using-api/req-res
아카이브 URL: (미수집)
저자 / 조직: 토스페이먼츠 (TossPayments) Developer Documentation
발행일: rolling docs
마지막 확인일: 2026-05-27

핵심 인용 / Key quotes (verbatim)

[§에러 객체 구조] "code: 에러 타입을 보여주는 에러 코드입니다."

[§에러 객체 구조] "message: 에러 메시지입니다."

[§응답 조건] "요청이 정상적으로 처리되지 않으면 응답으로 HTTP 상태 코드와 함께 아래와 같은 에러 객체가 돌아옵니다."

[§대표 에러 코드 — UNAUTHORIZED_KEY] "인증되지 않은 시크릿 키 혹은 클라이언트 키"

[§대표 에러 코드 — INVALID_REQUEST] "잘못된 요청입니다"

[§대표 에러 코드 — INVALID_REQUIRED_PARAM] "필수 파라미터가 누락되었습니다"

[§대표 에러 코드 — ALREADY_PROCESSED_PAYMENT] "이미 처리된 결제 입니다"

[§대표 에러 코드 — REJECT_CARD_PAYMENT] "한도초과 혹은 잔액부족으로 결제에 실패"

[§대표 에러 코드 — NOT_CANCELABLE_PAYMENT] "취소 할 수 없는 결제 입니다"

[§대표 에러 코드 — FAILED_INTERNAL_SYSTEM_PROCESSING] "내부 시스템 처리 작업이 실패"

[§대표 에러 코드 — PROVIDER_ERROR] "일시적인 오류가 발생했습니다"

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
TOSS-ERR-C1	에러 객체는 정확히 `{code, message}` 2개 필드로 구성 — `code` 는 에러 타입, `message` 는 에러 메시지	[§에러 객체 구조] "`code`: 에러 타입을 보여주는 에러 코드입니다." + "`message`: 에러 메시지입니다."	`official-vendor-doc`	토스페이먼츠 API 의 모든 error 응답	다른 필드 (`details`, `category`, `retryable`, `traceId` 등) 가 절대 없다는 뜻은 아님 — 본 페이지의 명시 범위에서 없음. traceId 는 별도 헤더로 제공될 가능성 (본 페이지에 명시 없음)
TOSS-ERR-C2	요청 실패 시 HTTP status code 와 함께 error 객체가 반환됨	[§응답 조건] "요청이 정상적으로 처리되지 않으면 응답으로 HTTP 상태 코드와 함께 아래와 같은 에러 객체가 돌아옵니다."	`official-vendor-doc`	토스페이먼츠 API 의 실패 응답	정확히 어떤 status code 가 어떤 code 와 매핑되는지의 전체 표는 본 인용에 없음 — 대표 코드만
TOSS-ERR-C3	인증 실패 시 `UNAUTHORIZED_KEY` 코드 — 인증되지 않은 시크릿/클라이언트 키 사용 시	[§대표 에러 코드 — UNAUTHORIZED_KEY] "인증되지 않은 시크릿 키 혹은 클라이언트 키"	`official-vendor-doc`	토스페이먼츠 API key 인증 단계	만료된 키 vs 비활성화 키의 분기는 본 인용에 없음
TOSS-ERR-C4	validation 실패 코드 어휘: `INVALID_REQUEST` (잘못된 요청), `INVALID_REQUIRED_PARAM` (필수 파라미터 누락)	[§대표 에러 코드 — INVALID_REQUEST] + [§대표 에러 코드 — INVALID_REQUIRED_PARAM] (위 인용)	`official-vendor-doc`	토스페이먼츠 API 의 schema validation 단계	GitHub 의 `missing_field` / `invalid` 등 6개 어휘 같은 fine-grained 분류는 없음 — 토스는 더 coarse
TOSS-ERR-C5	business rule 위반 코드 사례: `ALREADY_PROCESSED_PAYMENT` (이미 처리된 결제), `NOT_CANCELABLE_PAYMENT` (취소 불가 결제), `REJECT_CARD_PAYMENT` (한도초과/잔액부족)	[§대표 에러 코드 — ALREADY_PROCESSED_PAYMENT/NOT_CANCELABLE_PAYMENT/REJECT_CARD_PAYMENT] (위 인용)	`official-vendor-doc`	결제 도메인의 business rule 카탈로그	이 코드들이 retryable 인지 final 인지는 code 명만으로 추론. 명시적 `retryable` 필드 없음
TOSS-ERR-C6	시스템 / provider 오류 코드: `FAILED_INTERNAL_SYSTEM_PROCESSING` (내부 시스템 실패), `PROVIDER_ERROR` (일시적 오류)	[§대표 에러 코드 — FAILED_INTERNAL_SYSTEM_PROCESSING/PROVIDER_ERROR] (위 인용)	`official-vendor-doc`	토스 내부 / 카드사 등 외부 provider 오류 분리	client 가 retry 해야 할지 즉시 final 처리할지의 정확한 가이드는 본 인용에 없음 ("일시적" 이라는 표현으로 retry 유도만 시사)
TOSS-ERR-C7	에러 객체 안에 `traceId` 필드가 포함된다는 사실은 본 페이지 인용에는 명시 없음 — 별도 채널 (헤더?) 가능성	(부재 자체가 claim)	`needs-confirmation`	운영 디버깅 시 traceId 활용	traceId 가 없다는 뜻도 아님 — 본 페이지의 범위 밖. 별도 가이드 페이지 확인 필요

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것:
- TOSS-ERR-C1 ~ C6: 토스페이먼츠 error envelope 의 {code, message} 2-field 구조 + 대표 코드 어휘 (인증/validation/business rule/system)
이 자료가 증명하지 않는 것:
- 한국 결제 vendor 전체 (KG이니시스, 카카오페이, NHN KCP 등) 가 동일 패턴이라는 결론
- 토스가 i18n (영문 응답) 을 지원하는지 (본 페이지 한국어 메시지만)
- retryable 여부의 정확한 알고리즘 (코드명 + status 로 추론하는 수준)
- validation 다중 항목 오류의 표현 방식 ({code, message} 단일 → 다중 오류 합성 방식 불명)
- traceId 의 body 내 포함 여부 (C7)
- 성공 응답의 envelope 구조 (본 페이지는 error 만)
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- ca-tmpl 의 error.category / error.retryable 을 토스 코드 어휘에 매핑할 규칙
- 한국어 메시지 컨벤션 (예: "...입니다" 종결) 의 ca-tmpl 적용 여부
- validation 다중 오류 시 ca-tmpl error.details 활용

메모 / Notes

검증되지 않은 내 해석은 여기에 두지 말 것 — wiki source-summary 단계에서.

응답 shape 핵심:
```
{ "code": "NOT_FOUND_PAYMENT", "message": "존재하지 않는 결제 정보 입니다." }
```
- 매우 얇음. category/retryable/details/meta 모두 없음.
- 성공 응답은 리소스 직반환 (envelope X — 본 페이지에 명시 없음, 별도 페이지 확인).
- retryable 여부는 code semantic + HTTP status 로 추론 (e.g., PROVIDER_ERROR → 재시도 유도 메시지).
장점 (추론):
- 단순함. 한국어 메시지가 자연스러움.
- code-driven 카탈로그 (개발자센터에서 모든 코드 문서화).
- 학습 곡선 ↓ — 작은 팀/주니어 친화적.
단점 (추론):
- retryable, category, validation 항목별 풀이가 1급 영역에 없음.
- 다중 validation 오류 표현이 어려움 (단일 message 에 합쳐서 줘야 함).
- traceId 가 body 가 아닌 별도 채널일 가능성 (C7) — observability 컨벤션이 단편적.
ca-tmpl custom envelope 와의 차이:
- 토스: 매우 얇은 {code, message}, ca-tmpl: 더 두꺼운 {success, data, error.{code,category,message,retryable,details}, meta}.
- ca-tmpl 이 운영 메타데이터(retryable, category, meta) 를 1급으로 가져간 점이 정밀.
- 토스는 성공 응답에 envelope X, ca-tmpl 은 성공도 envelope.
표준 준수 / lock-in / client 호환성:
- RFC 7807 ProblemDetail 미준수. 한국 SI/결제 진영에서 사실상 컨벤션화.
- client 호환성: SDK 가 envelope 흡수 → 직접 사용자도 부담 낮음.
localization / i18n 지원 여부:
- 한국어 메시지 단일. Accept-Language 기반 분기 명시적이지 않음.

같은 주제 다른 raw:
- raw/company-tech-blogs/github-api-error-format — 영어권 vendor 사례 비교
- raw/company-tech-blogs/idempotency-toss-payments-techblog — 같은 vendor 의 idempotency 정책
- (RFC 7807 ProblemDetail / JSON:API / gRPC Status 자료는 별도)
인용하는 branch:
인용하는 project:
- raw/project-notes/ca-skeleton-operational-contract (§3, §6)
인용한 wiki 요약: (미작성)

10 KiB Raw Blame History