Skip to main content

이 버전의 GitHub Enterprise는 다음 날짜에 중단되었습니다. 2023-09-25. 중요한 보안 문제에 대해서도 패치 릴리스가 이루어지지 않습니다. 더 뛰어난 성능, 향상된 보안, 새로운 기능을 위해 최신 버전의 GitHub Enterprise Server로 업그레이드합니다. 업그레이드에 대한 도움말은 GitHub Enterprise 지원에 문의하세요.

REST API 문제 해결

REST API에 대한 일반적인 문제를 진단하고 해결하는 방법을 알아봅니다.

트래픽률 제한 오류

GitHub에서는 모든 사용자가 API를 사용할 수 있도록 트랙픽률 제한을 적용합니다. 자세한 내용은 "Rate limits for the REST API"을(를) 참조하세요.

기본 트래픽률 제한을 초과하면 403 Forbidden 또는 429 Too Many Requests 응답을 수신하며, x-ratelimit-remaining 헤더가 0이 됩니다. 보조 트래픽률 제한을 초과하는 경우 보조 트래픽률 제한을 초과했음을 나타내는 오류 메시지 및 403 Forbidden 또는 429 Too Many Requests 응답이 표시됩니다.

트래픽률 제한 오류를 수신하는 경우 다음 지침에 따라 일시적으로 요청을 중지해야 합니다.

  • retry-after 응답 헤더가 있는 경우 몇 초가 경과할 때까지 요청을 다시 시도하면 안 됩니다.
  • x-ratelimit-remaining 헤더가 0인 경우 x-ratelimit-reset 헤더로 지정된 시간까지 다른 요청을 시도해서는 안 됩니다. 헤더는 x-ratelimit-reset UTC Epoch 초 단위입니다.
  • 그렇지 않은 경우 다시 시도하기 전에 1분 이상 기다립니다. 보조 트래픽률 제한으로 인해 요청이 계속 실패하는 경우 재시도 사이에 기하급수적으로 증가하는 시간을 기다린 후 특정 횟수의 재시도 후 오류가 발생합니다.

트래픽률이 제한된 동안 요청을 계속하면 통합이 금지될 수 있습니다.

트래픽률 제한을 초과하지 않는 방법에 대한 자세한 내용은 "AUTOTITLE"을(를) 참조하세요.

기존 리소스에 대한 404 Not Found

프라이빗 리소스에 대한 액세스를 요청했지만 요청이 제대로 인증되지 않은 경우 404 Not Found 응답을 수신합니다. GitHub에서는 프라이빗 리포지토리의 존재를 확인하지 않도록 403 Forbidden 응답 대신 404 Not Found 응답을 사용합니다.

요청하는 리소스가 있음을 알고 있을 때 404 Not Found 응답을 수신하면 인증을 검사해야 합니다. 예시:

  • personal access token을(를) 사용하는 경우 다음을 확인해야 합니다.
    • 토큰에는 엔드포인트를 사용하는 데 필요한 범위가 있습니다. 자세한 내용은 "OAuth 앱에 대한 범위" 및 "개인용 액세스 토큰 관리"을(를) 참조하세요.
    • 토큰 소유자는 엔드포인트를 사용하는 데 필요한 모든 권한을 보유하고 있습니다. 예를 들어 조직 소유자만 엔드포인트를 사용할 수 있는 경우 영향을 받는 조직의 소유자인 사용자만 엔드포인트를 사용할 수 있습니다.
    • 토큰이 만료되거나 해지되지 않았습니다. 자세한 내용은 "토큰 만료 및 해지"을(를) 참조하세요.
  • GitHub App 설치 액세스 토큰을 사용하는 경우 다음을 확인해야 합니다.
    • GitHub App에는 엔드포인트를 사용하는 데 필요한 권한이 있습니다. 자세한 내용은 "GitHub 앱에 필요한 권한"을(를) 참조하세요.
    • 엔드포인트는 GitHub App이(가) 설치된 계정에서 소유한 리소스에만 영향을 줍니다.
    • GitHub App은(는) 엔드포인트의 영향을 받는 리포지토리에 액세스할 수 있습니다.
    • 토큰이 만료되거나 해지되지 않았습니다. 자세한 내용은 "토큰 만료 및 해지"을(를) 참조하세요.
  • GitHub App 사용자 액세스 토큰을 사용하는 경우 다음을 확인해야 합니다.
    • GitHub App에는 엔드포인트를 사용하는 데 필요한 권한이 있습니다. 자세한 내용은 "GitHub 앱에 필요한 권한"을(를) 참조하세요.
    • 토큰에 권한을 부여한 사용자는 엔드포인트를 사용하는 데 필요한 모든 권한을 보유하고 있습니다. 예를 들어 조직 소유자만 엔드포인트를 사용할 수 있는 경우 영향을 받는 조직의 소유자인 사용자만 엔드포인트를 사용할 수 있습니다.
    • GitHub App은(는) 엔드포인트의 영향을 받는 리포지토리에 액세스할 수 있습니다.
    • 사용자는 엔드포인트의 영향을 받는 모든 프라이빗 리포지토리에 대한 액세스 권한을 보유합니다.
    • 사용자가 GitHub App에 대한 업데이트된 권한을 승인했습니다. 자세한 내용은 "GitHub 앱에 대한 업데이트된 권한 승인"을(를) 참조하세요.
  • OAuth app 사용자 액세스 토큰을 사용하는 경우 다음을 확인해야 합니다.
    • 토큰에는 엔드포인트를 사용하는 데 필요한 범위가 있습니다. 자세한 내용은 "OAuth 앱에 대한 범위"을(를) 참조하세요.
    • 토큰에 권한을 부여한 사용자는 엔드포인트를 사용하는 데 필요한 모든 권한을 보유하고 있습니다. 예를 들어 조직 소유자만 엔드포인트를 사용할 수 있는 경우 영향을 받는 조직의 소유자인 사용자만 엔드포인트를 사용할 수 있습니다.
    • 조직에서 소유한 리소스에 영향을 주는 엔드포인트를 사용하는 경우 조직은 OAuth 앱 액세스를 차단하지 않습니다. 앱 소유자는 앱이 차단되었는지 여부를 확인할 수 없지만 앱 사용자에게 앱의 차단 여부를 확인할 것을 지시할 수 있습니다. 자세한 내용은 GitHub Free 설명서의 "OAuth 앱 액세스 제한 정보"을(를) 참조하세요.
    • 토큰이 만료되거나 해지되지 않았습니다. 자세한 내용은 "토큰 만료 및 해지"을(를) 참조하세요.
  • GitHub Actions 워크플로에서 GITHUB_TOKEN을(를) 사용하는 경우 다음을 확인해야 합니다.
    • 엔드포인트는 워크플로가 실행되는 리포지토리에서 소유한 리소스에만 영향을 줍니다. 조직이 소유한 리소스 또는 다른 리포지토리에서 소유한 리소스와 같이 해당 리포지토리 외부의 리소스에 액세스해야 하는 경우 personal access token 또는 GitHub App에 대한 액세스 토큰을 사용해야 합니다.

인증에 대한 자세한 내용은 "REST API에 인증"(을)를 참조하세요.

URL에 오타가 있는지도 검사해야 합니다. 예를 들어 엔드포인트에 후행 슬래시를 추가하면 404 Not Found 오류가 발생합니다. 엔드포인트에 대한 참조 설명서를 참조하여 URL이 올바른지 확인할 수 있습니다.

누락된 결과

리소스 목록을 반환하는 대부분의 엔드포인트는 페이지 매김을 지원합니다. 대부분의 엔드포인트에서는 처음 30개의 리소스만 기본값으로 반환됩니다. 모든 리소스를 보려면 결과에 페이지 매김을 적용해야 합니다. 자세한 내용은 "REST API에서 페이지 매김 사용"을(를) 참조하세요.

페이지 매김을 올바르게 사용하고 있지만 예상한 결과가 모두 표시되지 않는 경우 사용한 인증 자격 증명이 모든 예상 리소스에 대한 액세스 권한을 보유하는지 확인해야 합니다. 예를 들어 GitHub App 설치 액세스 토큰을 사용하는 경우 조직의 리포지토리 하위 집합에 대한 액세스 권한만 설치에 부여되었으면 해당 조직의 모든 리포지토리에 대한 요청은 앱 설치에서 액세스할 수 있는 리포지토리만 반환합니다.

시간 제한

GitHub Enterprise Server에서 API 요청을 처리하는 데 10초를 초과하는 경우 GitHub Enterprise Server에서는 요청을 종료하고 사용자는 시간 제한 응답 및 "서버 오류" 메시지를 수신합니다.

GitHub Enterprise Server는 API의 속도와 안정성을 보호하기 위해 시간 제한 기간을 변경할 수 있는 권한이 있습니다.

githubstatus.com에서 RESTP API 상태를 확인하여 시간 제한이 API 관련 문제로 인해 발생하는지 여부를 확인할 수 있습니다. 요청을 간소화하거나 나중에 요청을 시도할 수도 있습니다. 예를 들어 페이지에서 100개의 항목을 요청하는 경우 더 적은 수의 항목을 요청할 수 있습니다.

리소스에 액세스할 수 없음

GitHub App을(를) 사용하는 경우 "통합을 통해 리소스에 액세스할 수 없음" 오류를 수신하면 토큰에 권한이 부족한 것입니다. 각 엔드포인트에 필요한 권한에 대한 자세한 내용은 "GitHub 앱에 필요한 권한"을(를) 참조하세요.

JSON 구문 분석 문제

요청 본문에서 잘못된 JSON을 보내는 경우 400 Bad Request 응답 및 "JSON 구문 분석 문제" 오류 메시지가 수신될 수 있습니다. Linter 또는 JSON 유효성 검사기를 사용하여 JSON에서 오류를 식별할 수 있습니다.

본문은 JSON 개체여야 함

엔드포인트에서 JSON 개체를 예상하지만 요청 본문의 형식을 JSON 개체로 지정하지 않으면 400 Bad Request 응답 및 "본문은 JSON 개체여야 함" 오류 메시지를 수신할 수 있습니다.

잘못된 요청

필수 매개 변수를 생략하거나 잘못된 유형의 매개 변수를 사용하는 경우 422 Unprocessable Entity 응답 및 "잘못된 요청" 오류 메시지를 수신할 수 있습니다. 예를 들어 매개 변수 값을 배열로 지정하지만 엔드포인트에 문자열이 있는 경우 이 오류가 발생합니다. 엔드포인트에 대한 참조 설명서를 참조하여 올바른 매개 변수 유형을 사용하고 있으며 모든 필수 매개 변수를 포함하고 있는지 확인할 수 있습니다.

유효성 검사 실패

요청을 처리할 수 없는 경우 422 Unprocessable Entity 응답 및 "유효성 검사 실패" 오류 메시지를 수신할 수 있습니다. 응답 본문에는 문제를 진단하는 데 도움이 되는 code 속성이 있는 errors 속성이 포함됩니다.

코드설명
missing리소스가 존재하지 않습니다.
missing_field필요한 매개 변수를 지정하지 않았습니다. 엔드포인트에 대한 설명서를 검토하여 필요한 매개 변수를 확인합니다.
invalid매개 변수 서식이 잘못 지정되었습니다. 자세한 내용은 엔드포인트 설명서를 검토하세요.
already_exists다른 리소스의 값이 매개 변수 값 중 하나와 동일합니다. 이 오류는 일부 고유 키(예: 레이블 이름)가 있어야 하는 리소스에서 발생할 수 있습니다.
unprocessable제공된 매개 변수가 잘못되었습니다.
custom오류를 진단하려면 message 속성을 참조하세요.

사용자 에이전트 필요

올바른 User-Agent 헤더가 없는 요청은 거부됩니다. User-Agent 값에 사용자 이름 또는 애플리케이션의 이름을 사용해야 합니다.

curl은 기본적으로 유효한 User-Agent 헤더를 보냅니다.

기타 오류

여기서 해결되지 않은 오류가 발생하는 경우 API에서 제공하는 오류 메시지를 참조해야 합니다. 대부분의 오류 메시지에서는 잘못된 내용에 대한 단서와 관련 설명서에 대한 링크를 제공합니다.

예기치 않은 오류가 발생하는 경우 githubstatus.com에서 REST API 상태를 확인할 수 있습니다.

추가 참고 자료