donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
58515ab0f3c9b94ed48e9efe7a11bb52c169ce83
llm-wiki/raw/company-tech-blogs/github-api-error-format.md
T

9.3 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
GitHub REST API Error Format company-tech-blog https://docs.github.com/en/rest/using-the-rest-api/troubleshooting-the-rest-api raw high
ca-error-envelope
github
custom-envelope
rest-api
vendor-api
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

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

핵심 인용 / 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 참조):

    {
  "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 / 관련

Reference in New Issue View Git Blame Copy Permalink