---
title: GitHub REST API Error Format
source_type: company-tech-blog
url: https://docs.github.com/en/rest/using-the-rest-api/troubleshooting-the-rest-api
archive_url:
status: raw
confidence: high
tags: [ca-error-envelope, github, custom-envelope, rest-api, vendor-api]
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
---

# GitHub REST API Error Format

> Layer: `raw/company-tech-blogs/` — GitHub REST API 공식 vendor 레퍼런스 (docs.github.com). `source_type` 은 `company-tech-blog` 디렉토리이나 strength 는 `official-vendor-doc` (vendor API reference 등급). 자동 mv 금지 규칙으로 디렉토리 유지 — 후속 정리 권고.
> 검증된 요약은 `/ingest` 후 `wiki/concepts/`에 별도 작성.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-operational-error-observability-foundation]] | error envelope 구조 결정 시 GitHub 의 `{message, errors[]}` 평면 모델 비교 base |
| [[raw/branch-notes/feature-boundary-validation-mapping-contract]] | validation 오류 항목별 풀이 (`resource/field/code`) 의 vendor reference. ca-tmpl `error.details` 와 직접 대조 |
| [[raw/branch-notes/feature-business-rule-validation-contract]] | validation code 어휘 (`missing/missing_field/invalid/already_exists/unprocessable/custom`) 의 표준 사례 |
| [[raw/project-notes/ca-skeleton-operational-contract]] | §3. Structured API Response Contract + §6. Operational Error Category 의 대안 비교 base |

## 컨텍스트

GitHub 은 대형 public REST API 의 사실상 표준 사례 중 하나. validation 오류를 어떻게 항목별로 풀어내는지 (`errors[].field/code`) 가 ca-tmpl 의 `error.details` 와 직접 대조됨.

## 출처 / Source

- 원본 URL: https://docs.github.com/en/rest/using-the-rest-api/troubleshooting-the-rest-api
- 아카이브 URL: (미수집)
- 저자 / 조직: GitHub Inc. (Microsoft) — official REST API documentation
- 발행일: rolling docs
- 마지막 확인일: 2026-05-27

## 핵심 인용 / Key quotes (verbatim)

> [§Errors property] "The response body will include an `errors` property, which includes a `code` property to help you diagnose the problem."

> [§400 Bad Request] "If you send invalid JSON in the request body, you may receive a `400 Bad Request` response and a 'Problems parsing JSON' error message."

> [§422 Unprocessable Entity] "If you omit required parameters or you use the wrong type for a parameter, you may receive a `422 Unprocessable Entity` response and an 'Invalid request' error message."

> [§Validation error codes] "`missing`: A resource does not exist."

> [§Validation error codes] "`missing_field`: A parameter that was required was not specified."

> [§Validation error codes] "`invalid`: The formatting of a parameter is invalid."

> [§Validation error codes] "`already_exists`: Another resource has the same value as one of your parameters."

> [§Validation error codes] "`unprocessable`: The parameters that were provided were invalid."

> [§Validation error codes] "`custom`: Refer to the `message` property to diagnose the error."

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| GH-ERR-C1 | error response body 는 `errors` property 를 포함하며, 각 항목에 진단용 `code` property 가 있다 | [§Errors property] "The response body will include an `errors` property, which includes a `code` property to help you diagnose the problem." | `official-vendor-doc` | GitHub REST API 의 모든 error 응답 | top-level 에 `code` 가 있다는 뜻은 아님 (`code` 는 `errors[]` 항목 내부). 정확한 JSON 스키마 전체는 본 인용에 없음 |
| GH-ERR-C2 | 잘못된 JSON body 는 `400 Bad Request` + "Problems parsing JSON" 메시지로 응답 | [§400 Bad Request] "If you send invalid JSON in the request body, you may receive a `400 Bad Request` response and a 'Problems parsing JSON' error message." | `official-vendor-doc` | GitHub REST API request body parsing 단계 | 모든 400 응답이 parsing 오류라는 뜻은 아님. 400 의 다른 원인 (예: rate limit 관련) 은 별도 |
| GH-ERR-C3 | 필수 파라미터 누락 또는 잘못된 타입은 `422 Unprocessable Entity` + "Invalid request" 메시지 | [§422 Unprocessable Entity] "If you omit required parameters or you use the wrong type for a parameter, you may receive a `422 Unprocessable Entity` response and an 'Invalid request' error message." | `official-vendor-doc` | GitHub REST API 의 schema validation 단계 | 422 가 RFC 9110 의 모든 unprocessable 의미를 그대로 따른다는 뜻은 아님 — vendor-specific 사용 |
| GH-ERR-C4 | validation error code 어휘는 정확히 6개: `missing`, `missing_field`, `invalid`, `already_exists`, `unprocessable`, `custom` — 각 정의가 공식 명시됨 | [§Validation error codes] 6개 코드의 verbatim 정의 (위 인용) | `official-vendor-doc` | GitHub REST API client 가 응답 처리 시 분기하는 코드 집합 | 이 6개가 모든 REST API 의 표준 어휘라는 뜻은 아님. GitHub-specific |
| GH-ERR-C5 | `custom` code 는 `message` property 를 참조하여 진단 — 즉 카탈로그 외 오류는 message-driven | [§Validation error codes] "`custom`: Refer to the `message` property to diagnose the error." | `official-vendor-doc` | GitHub REST API 의 escape hatch 메커니즘 | client 가 `custom` 메시지로 자동 분기할 수 있다는 뜻은 아님 — i18n 위험 + parse 불가 |
| GH-ERR-C6 | 응답에 `documentation_url` 이 포함된다는 사실은 troubleshooting 페이지 본 인용에는 **명시 없음** (다른 GitHub docs 페이지에서 별도 확인 필요) | (부재 자체가 claim) | `needs-confirmation` | top-level 응답 shape | `documentation_url` 이 없다는 뜻도 아님 — 본 페이지의 범위 밖. 관행적으로 알려진 형태일 뿐 |

## Usage Boundaries / 적용 경계

- **이 자료가 직접 증명하는 것**:
  - `GH-ERR-C1` ~ `C5`: GitHub REST API 의 error response 구조, status code 매핑, validation 코드 어휘
- **이 자료가 증명하지 않는 것**:
  - 정확한 top-level JSON 스키마 (예: `{message, documentation_url, errors[]}`) — 본 페이지에 완전한 예시 없음 (`C6`)
  - `errors[]` 항목의 정확한 필드 (`resource`, `field`, `message?`) — 일부만 명시
  - retryable 정보 제공 여부 (본 페이지에 없음)
  - i18n 지원 (영문 메시지 외 분기 여부)
  - 성공 응답의 envelope 구조
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
  - ca-tmpl 의 `error.category` / `error.retryable` 에 매핑할 GitHub 측 어휘가 없음을 어떻게 처리할지
  - ca-tmpl 의 단일 `error` 객체 + `details` vs GitHub 의 top-level 평면 + `errors[]` array 의 client 호환성
  - `documentation_url` 활용 (RFC 7807 `type` URI 와 유사한 역할)

## 메모 / Notes

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

- 응답 shape 핵심 (관행적으로 알려진 형태, 본 페이지가 완전한 JSON 예시는 안 줌 — `C6` 참조):
  ```json
  {
    "message": "Validation Failed",
    "documentation_url": "https://docs.github.com/rest/...",
    "errors": [
      { "resource": "Issue", "field": "title", "code": "missing_field" }
    ]
  }
  ```
  - top-level 은 단순한 `{message, documentation_url, errors[]}` (관행).
  - `errors[]` 각각은 `{resource, field, code, message?}` (관행).

- 장점 (추론):
  - 매우 얕고 읽기 쉬움. curl 로 디버깅하기 좋음.
  - `documentation_url` 이 RFC 7807 `type` URI 와 같은 역할 (관행적 형태 가정).
  - validation 오류를 항목 단위로 풀어서 form UX 매핑 용이.

- 단점 (추론):
  - top-level `code`/`category` 가 없음 — client 는 HTTP status 에 더 의존.
  - retryable 정보 없음 → `Retry-After` 헤더로만 신호 (별도).
  - 성공 응답은 envelope 없음 (리소스 직반환).

- ca-tmpl custom envelope 와의 차이:
  - ca-tmpl 은 단일 `error` 객체 + `details`, GitHub 은 top-level 평면 + `errors` array. 표현력은 유사하나 항목 단위 오류는 GitHub 이 더 명시적.
  - ca-tmpl 의 `category` / `retryable` 은 GitHub 에는 없음.

- 표준 준수 / lock-in / client 호환성:
  - RFC 7807 ProblemDetail 미준수. 그러나 단순성 덕에 학습 곡선 ↓, octokit 등 SDK 가 envelope 을 흡수.

- localization / i18n 지원 여부:
  - 별도 i18n 표준 없음. 영문 메시지 고정.

## Related / 관련

- 같은 주제 다른 raw:
  - [[raw/company-tech-blogs/toss-payments-error-format]] — 한국 vendor 사례 비교
  - (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 요약: (미작성)