donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
55de4f55b037af9554af9007ce834030ac7e729e
llm-wiki/raw/official-docs/graphql-errors-spec.md
T

9.8 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 tags related_projects related_branches created last_reviewed
GraphQL Specification — Errors (Section 7.1.2) official-doc https://spec.graphql.org/October2021/#sec-Errors raw high
ca-error-envelope
graphql
spec
error-format
partial-success
official-doc
ca-skeleton-operational-contract
feature-operational-error-observability-foundation
feature-boundary-validation-mapping-contract
feature-business-rule-validation-contract
2026-05-22 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

핵심 인용 / 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 예시 (해석/구성): 
    {
  "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 / 관련

Reference in New Issue View Git Blame Copy Permalink