141 lines
10 KiB
Markdown
141 lines
10 KiB
Markdown
---
|
|
title: 토스페이먼츠 API Error Format
|
|
source_type: company-tech-blog
|
|
url: https://docs.tosspayments.com/reference/error-codes
|
|
archive_url:
|
|
status: raw
|
|
confidence: high
|
|
tags: [ca-error-envelope, toss, korean-api, custom-envelope, rest-api, korean-fintech]
|
|
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
|
|
---
|
|
|
|
# 토스페이먼츠 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 핵심:
|
|
```json
|
|
{ "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` 기반 분기 명시적이지 않음.
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 다른 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:
|
|
- [[raw/branch-notes/feature-operational-error-observability-foundation]]
|
|
- [[raw/branch-notes/feature-boundary-validation-mapping-contract]]
|
|
- [[raw/branch-notes/feature-business-rule-validation-contract]]
|
|
- 인용하는 project:
|
|
- [[raw/project-notes/ca-skeleton-operational-contract]] (§3, §6)
|
|
- 인용한 wiki 요약: (미작성)
|