---
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: (미작성)