REST API 문제 해결

트래픽률 제한 오류

GitHub에서는 모든 사용자가 API를 사용할 수 있도록 트랙픽률 제한을 적용합니다. 자세한 내용은 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분 이상 기다립니다. 보조 트래픽률 제한으로 인해 요청이 계속 실패하는 경우 재시도 사이에 기하급수적으로 증가하는 시간을 기다린 후 특정 횟수의 재시도 후 오류가 발생합니다.

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

트래픽률 제한을 초과하지 않는 방법에 대한 자세한 내용은 REST API 사용에 대한 모범 사례을(를) 참조하세요.

기존 리소스에 대한 `404 Not Found`

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

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

personal access token (classic)을(를) 사용하는 경우 다음을 확인해야 합니다.
- 토큰에는 엔드포인트를 사용하는 데 필요한 범위가 있습니다. 자세한 내용은 OAuth 앱에 대한 범위 및 개인용 액세스 토큰 관리을(를) 참조하세요.
- 토큰 소유자는 엔드포인트를 사용하는 데 필요한 모든 권한을 보유하고 있습니다. 예를 들어 조직 소유자만 엔드포인트를 사용할 수 있는 경우 영향을 받는 조직의 소유자인 사용자만 엔드포인트를 사용할 수 있습니다.
- 토큰이 만료되거나 해지되지 않았습니다. 자세한 내용은 토큰 만료 및 해지을(를) 참조하세요.
fine-grained personal access token을(를) 사용하는 경우 다음을 확인해야 합니다.
- 토큰에는 엔드포인트를 사용하는 데 필요한 권한이 있습니다. 필요한 권한에 대한 자세한 내용은 해당 엔드포인트에 대한 설명서를 참조하세요.
- 토큰에 대해 지정된 리소스 소유자는 엔드포인트의 영향을 받는 리소스의 소유자와 일치합니다. 자세한 내용은 개인용 액세스 토큰 관리을(를) 참조하세요.
- 토큰은 엔드포인트의 영향을 받는 모든 프라이빗 리포지토리에 대한 액세스 권한을 보유합니다. 자세한 내용은 개인용 액세스 토큰 관리을(를) 참조하세요.
- 토큰 소유자는 엔드포인트를 사용하는 데 필요한 모든 권한을 보유하고 있습니다. 예를 들어 조직 소유자만 엔드포인트를 사용할 수 있는 경우 영향을 받는 조직의 소유자인 사용자만 엔드포인트를 사용할 수 있습니다.
- 토큰이 만료되거나 해지되지 않았습니다. 자세한 내용은 토큰 만료 및 해지을(를) 참조하세요.
GitHub App 설치 액세스 토큰을 사용하는 경우 다음을 확인해야 합니다.
- GitHub App에는 엔드포인트를 사용하는 데 필요한 권한이 있습니다. 필요한 권한에 대한 자세한 내용은 해당 엔드포인트에 대한 설명서를 참조하세요.
- 엔드포인트는 GitHub App이(가) 설치된 계정에서 소유한 리소스에만 영향을 줍니다.
- GitHub App은(는) 엔드포인트의 영향을 받는 리포지토리에 액세스할 수 있습니다.
- 토큰이 만료되거나 해지되지 않았습니다. 자세한 내용은 토큰 만료 및 해지을(를) 참조하세요.
GitHub App 사용자 액세스 토큰을 사용하는 경우 다음을 확인해야 합니다.
- GitHub App에는 엔드포인트를 사용하는 데 필요한 권한이 있습니다. 필요한 권한에 대한 자세한 내용은 해당 엔드포인트에 대한 설명서를 참조하세요.
- 토큰에 권한을 부여한 사용자는 엔드포인트를 사용하는 데 필요한 모든 권한을 보유하고 있습니다. 예를 들어 조직 소유자만 엔드포인트를 사용할 수 있는 경우 영향을 받는 조직의 소유자인 사용자만 엔드포인트를 사용할 수 있습니다.
- 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이 올바른지 확인할 수 있습니다.

또한 모든 경로 매개 변수는 URL로 인코딩되어야 합니다. 예를 들어 매개 변수 값의 슬래시를 %2F(으)로 대체해야 합니다. 매개 변수 이름에 슬래시를 제대로 인코딩하지 않으면 엔드포인트 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 또는 fine-grained personal access token을(를) 사용하는 경우 "통합을 통해 리소스에 액세스할 수 없음" 또는 "personal access token을(를) 통해 리소스에 액세스할 수 없음" 오류를 수신하면 토큰에 권한이 부족한 것입니다. 필요한 권한에 대한 자세한 내용은 해당 엔드포인트에 대한 설명서를 참조하세요.

X-Accepted-GitHub-Permissions 헤더를 사용하여 REST API 엔드포인트에 액세스하는 데 필요한 권한을 식별할 수 있습니다.

X-Accepted-GitHub-Permissions 헤더 값은 엔드포인트를 사용하는 데 필요한 사용 권한의 쉼표로 구분된 목록입니다. 경우에 따라 여러 권한 집합 중에서 선택할 수 있습니다. 이러한 경우 쉼표로 구분된 여러 목록은 세미콜론으로 구분됩니다.

예시:

X-Accepted-GitHub-Permissions: contents=read는 GitHub App 또는 fine-grained personal access token이(가) 콘텐츠 권한에 대한 읽기 권한이 필요하다는 것을 의미합니다.
X-Accepted-GitHub-Permissions: pull_requests=write,contents=read는 GitHub App 또는 fine-grained personal access token이(가) 끌어오기 요청 권한에 대한 쓰기 권한 및 콘텐츠 권한에 대한 읽기 권한이 필요하다는 것을 의미합니다.
X-Accepted-GitHub-Permissions: pull_requests=read,contents=read; issues=read,contents=read는 GitHub App 또는 fine-grained personal access token이(가) 끌어오기 요청 권한에 대한 읽기 권한 및 콘텐츠 권한에 대한 읽기 권한 또는 이슈 권한에 대한 읽기 권한 또는 콘텐츠 권한에 대한 읽기 권한이 필요하다는 것을 의미합니다.

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` 속성을 참조하세요.

지원되지 않는 버전

X-GitHub-Api-Version 헤더를 사용하여 API 버전을 지정해야 합니다. 예시:

curl --header "X-GitHub-Api-Version:2022-11-28" https://api.github.com/zen

존재하지 않는 버전을 지정하면 400 Bad Request 오류 및 지원되지 않는 버전에 대한 메시지를 수신합니다.

자세한 내용은 API 버전을(를) 참조하세요.