130 lines
9.8 KiB
Markdown
130 lines
9.8 KiB
Markdown
---
|
|
title: GraphQL Specification — Errors (Section 7.1.2)
|
|
source_type: official-doc
|
|
url: https://spec.graphql.org/October2021/#sec-Errors
|
|
archive_url:
|
|
status: raw
|
|
confidence: high
|
|
tags: [ca-error-envelope, graphql, spec, error-format, partial-success, official-doc]
|
|
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
|
|
---
|
|
|
|
# GraphQL Specification — Errors (Section 7.1.2)
|
|
|
|
> Layer: `raw/official-docs/` — GraphQL Specification (October 2021), Section 7 Response / 7.1.2 Errors. WebFetch 가 `spec.graphql.org` 에 대해 HTTP 403 → 동일 spec 의 정식 source 인 `graphql/graphql-spec` GitHub repo (`spec/Section 7 -- Response.md`) 에서 verbatim quote 보강.
|
|
> ca-tmpl Topic 4 (Error Envelope) 의 **대안 4 (GraphQL errors array)** 비교 근거.
|
|
|
|
## Parent / 활용 branch (필수)
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/branch-notes/feature-operational-error-observability-foundation]] | ca-tmpl Topic 4 (Error Envelope) 대안 비교 — GraphQL 의 `data`+`errors` 공존 모델 (partial success 1급) 의 표준 근거 |
|
|
| [[raw/branch-notes/feature-boundary-validation-mapping-contract]] | 경계(boundary) 입력 검증 실패 시 `path` 기반 필드 매핑 옵션의 GraphQL 표준 근거 |
|
|
| [[raw/branch-notes/feature-business-rule-validation-contract]] | business rule 실패의 `extensions` free-form 확장 모델 비교 — ca-tmpl 의 `meta`/`category` 와 대응 평가 |
|
|
|
|
## 컨텍스트 / 왜 저장했는지
|
|
|
|
GraphQL 은 transport 전체가 HTTP 200 으로 묶이고 오류는 `errors` array 로만 신호. REST envelope 과 가장 다른 패러다임 → ca-tmpl 이 REST 를 택했을 때 무엇을 포기하지 않았는지 확인. partial success 가 1급 개념인 점이 5개 대안 중 GraphQL 만의 차별점.
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL: https://spec.graphql.org/October2021/#sec-Errors (WebFetch 403)
|
|
- 1차 verbatim source (보강): https://github.com/graphql/graphql-spec/blob/main/spec/Section%207%20--%20Response.md
|
|
- 아카이브 URL: (미수집)
|
|
- 저자 / 조직: GraphQL Foundation
|
|
- 발행일: GraphQL Specification — October 2021 edition (보강 본은 `main` 브랜치 working draft — 두 본문은 7.1.2 핵심 진술 동일)
|
|
- 마지막 확인일: 2026-05-27
|
|
|
|
## 핵심 인용 / Key quotes (verbatim)
|
|
|
|
> [§7.1.2 Errors — message required] "Every error must contain an entry with the key {\"message\"} with a string description of the error intended for the developer as a guide to understand and correct the error."
|
|
|
|
> [§7.1.2 Errors — locations / path / extensions] "If an error can be associated to a particular point in the requested GraphQL document, it should contain an entry with the key {\"locations\"}..." ... "If an error can be associated to a particular field in the GraphQL result, it must contain an entry with the key {\"path\"}..." ... "GraphQL services may provide an additional entry to errors with key `extensions`."
|
|
|
|
> [§7.1.2 Errors — partial response with data + errors] "A response may contain both a partial response as well as a list of errors in the case that any _execution error_ was raised and replaced with {null}."
|
|
|
|
> [§7.1.2 Errors — extensions as unrestricted map] "This entry, if set, must have a map as its value... there are no additional restrictions on its contents."
|
|
|
|
## Claims Extracted / 추출된 주장
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| GQL-ERR-C1 | 모든 error 객체는 **`message`** 엔트리 (개발자 대상 문자열) 를 반드시 포함해야 함 | [§7.1.2 Errors — message required] "Every error must contain an entry with the key {\"message\"} with a string description of the error intended for the developer as a guide to understand and correct the error." | `official-standard` | GraphQL spec 준수 응답의 모든 error 객체 | `message` 가 사용자(end-user) 표시용이라는 뜻은 아님 — "developer" 명시 |
|
|
| GQL-ERR-C2 | error 객체는 선택적으로 `locations` (요청 문서 내 위치), `path` (결과 필드 경로), `extensions` (자유 확장 맵) 을 가질 수 있음 | [§7.1.2 Errors — locations / path / extensions] "If an error can be associated to a particular point in the requested GraphQL document, it should contain an entry with the key {\"locations\"}..." + "If an error can be associated to a particular field in the GraphQL result, it must contain an entry with the key {\"path\"}..." + "GraphQL services may provide an additional entry to errors with key `extensions`." | `official-standard` | GraphQL response error 객체의 부가 필드 | `path` 가 항상 1개 path 라는 뜻은 아님 (array of segments) — 인용 범위 밖 |
|
|
| GQL-ERR-C3 | execution error 가 `null` 로 치환되었을 때 응답에 **`data` (partial) + `errors` 가 공존** 할 수 있음 (partial response 1급) | [§7.1.2 Errors — partial response with data + errors] "A response may contain both a partial response as well as a list of errors in the case that any _execution error_ was raised and replaced with {null}." | `official-standard` | execution-phase 실패에 의한 partial response | validation/parse 실패에서도 partial 이 발생한다는 뜻은 아님 — execution error 한정 |
|
|
| GQL-ERR-C4 | `extensions` 엔트리는 **map** 이어야 하며, **내용 형식에 추가 제약이 없음** (free-form custom 확장) | [§7.1.2 Errors — extensions as unrestricted map] "This entry, if set, must have a map as its value... there are no additional restrictions on its contents." | `official-standard` | server 의 custom 메타데이터 (`code`, `category`, `retryable` 등) 노출 방법 | spec 이 특정 키 (e.g., `extensions.code`) 를 표준으로 정의했다는 뜻은 아님 — 컨벤션은 server 별 |
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
- **이 자료가 직접 증명하는 것**:
|
|
- `GQL-ERR-C1`: `message` 의 필수성과 "developer 대상" 의도
|
|
- `GQL-ERR-C2`: `locations` / `path` / `extensions` 의 spec 정의된 의미
|
|
- `GQL-ERR-C3`: `data` 와 `errors` 의 spec 차원 공존 가능성 (partial response 1급 패러다임)
|
|
- `GQL-ERR-C4`: `extensions` 의 free-form map 성격
|
|
- **이 자료가 증명하지 않는 것**:
|
|
- HTTP status code 활용 정책 — GraphQL 은 본 spec 차원에서 HTTP 를 규정하지 않음 (별도 graphql-over-http spec)
|
|
- `extensions.code` / `extensions.category` 같은 **표준 키** 의 존재 — server/library 별 컨벤션 (Apollo `errors.extensions.code` 등)
|
|
- `retryable` 같은 운영 친화적 키의 spec 표준 존재 (없음 → server 마다 다른 형태)
|
|
- 원본 raw doc 의 "Errors during validation often contain multiple locations, for example to point out two things with the same name" 인용은 본 fetch 에서 verbatim 재확인 못 함 — 별도 spec subsection 또는 historical edition 가능성 → `needs-confirmation`
|
|
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
|
|
- REST 기반 ca-tmpl 에서 partial success 표현이 필요한 use case 가 있는지 (없다면 GraphQL 모델 채택 동기 부족)
|
|
- `extensions.category` / `extensions.retryable` 같은 ad-hoc 키를 사용할 경우 server/client 간 컨벤션 문서화 (별도)
|
|
- HTTP status 와 GraphQL `errors` 의 매핑 정책 (graphql-over-http spec 별도)
|
|
|
|
## 메모 / Notes (내 프로젝트 해석)
|
|
|
|
> 본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.
|
|
|
|
- 응답 shape 예시 (해석/구성):
|
|
```json
|
|
{
|
|
"data": { "user": null },
|
|
"errors": [
|
|
{
|
|
"message": "User not found",
|
|
"locations": [{"line": 2, "column": 3}],
|
|
"path": ["user"],
|
|
"extensions": {
|
|
"code": "USER_NOT_FOUND",
|
|
"category": "client",
|
|
"retryable": false
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
- HTTP 는 보통 200. transport-level 실패만 4xx/5xx
|
|
- `extensions` 가 사실상 ca-tmpl 의 `error` 객체에 대응
|
|
- **장점 (해석)**:
|
|
- partial success 가 1급 → 여러 필드 중 일부만 실패해도 자연스러움
|
|
- `path` 로 어떤 필드가 실패했는지 명시
|
|
- `extensions` free-form → custom 메타데이터 추가 비용 0
|
|
- **단점 (해석)**:
|
|
- HTTP status code 활용 ↓ → CDN/proxy/observability 도구의 4xx/5xx 기반 알람과 부조화
|
|
- REST envelope 과 직접 비교 어려움 — 패러다임 자체가 다름
|
|
- retryable/category 는 spec 외 → 결국 server 마다 다른 `extensions` 스키마
|
|
- **ca-tmpl custom envelope 와의 차이 (해석)**:
|
|
- ca-tmpl: REST + HTTP status code + `success` flag
|
|
- GraphQL: 단일 transport (HTTP 200), `data`/`errors` 공존
|
|
- ca-tmpl 의 `meta` 는 GraphQL `extensions` 에 가까움
|
|
- **표준 준수 / lock-in / client 호환성 (해석)**:
|
|
- GraphQL 진영 표준. Apollo/Relay 등 client 가 `errors` 처리 표준화
|
|
- REST 프로젝트 (ca-tmpl) 와는 호환 영역 자체가 다름
|
|
- **localization / i18n 지원 여부 (해석)**:
|
|
- spec 차원 i18n 없음. `extensions.locale` 같은 컨벤션을 각 server 가 만듦
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 다른 official-doc / company-tech-blog:
|
|
- [[raw/official-docs/spring-problem-detail]] (대안 1 구현체 — RFC 7807/9457)
|
|
- [[raw/official-docs/google-api-error-format]] (대안 2 — gRPC `google.rpc.Status`)
|
|
- [[raw/official-docs/json-api-errors-spec]] (대안 3 — JSON:API errors)
|
|
- [[raw/company-tech-blogs/stripe-error-format]] (대안 5 — Stripe custom envelope)
|
|
- 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, **대안 4: GraphQL errors array**
|
|
- 인용하는 wiki: (미작성)
|