REST API를 사용할 때 문제가 발생할 수 있습니다.

문제 해결하려면 REST API 상태 코드를 참조합니다. HTTP 응답 헤더와 종료 코드를 포함하는 것도 도움이 될 수 있습니다.

상태 코드#

GitLab REST API는 컨텍스트와 작업에 따라 모든 응답과 함께 상태 코드를 반환합니다. 요청에서 반환된 상태 코드는 문제 해결 시 유용할 수 있습니다.

다음 표는 API가 일반적으로 동작하는 방식에 대한 개요를 제공합니다.

다음 표는 API 요청에 대한 가능한 반환 코드를 보여줍니다.

상태 코드 400#

API를 사용할 때 유효성 검사 오류가 발생할 수 있으며, 이 경우 API가 HTTP 400 오류를 반환합니다.

이러한 오류는 다음 경우에 발생합니다:

• API 요청의 필수 속성이 없는 경우(예: 이슈의 제목이 제공되지 않은 경우).
• 속성이 유효성 검사를 통과하지 못한 경우(예: 사용자 소개가 너무 긴 경우).

속성이 없을 때 다음과 같은 응답을 받습니다:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "message":"400 (Bad request) \"title\" not given"
}

유효성 검사 오류가 발생하면 오류 메시지가 다릅니다. 유효성 검사 오류의 모든 세부 정보를 포함합니다:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "message": {
        "bio": [
            "is too long (maximum is 255 characters)"
        ]
    }
}

이렇게 하면 오류 메시지를 더 기계가 읽기 쉽게 만듭니다. 형식은 다음과 같이 설명할 수 있습니다:

{
    "message": {
        "<property-name>": [
            "<error-message>",
            "<error-message>",
            ...
        ],
        "<embed-entity>": {
            "<property-name>": [
                "<error-message>",
                "<error-message>",
                ...
            ],
        }
    }
}

상태 코드 401#

API는 다음과 같은 경우에 401 Unauthorized 오류를 반환합니다.

• 작업에 인증이 필요한데 요청에 토큰이 포함되어 있지 않은 경우.
• 작업에 인증이 필요한데 요청에 유효하지 않은 액세스 토큰이 포함된 경우. 예를 들어 토큰이 존재하지 않거나, 만료되었거나, 폐기된 경우입니다.
• 일부 작업에서 요청에 유효한 액세스 토큰이 포함되어 있지만 사용자에게 올바른 권한이 없는 경우. 예를 들어 머지 리퀘스트를 머지할 권한이 없거나 다른 사용자의 개인 액세스 토큰을 나열할 권한이 없는 경우입니다.

토큰이 없는 요청, 존재하지 않는 토큰, 그리고 두 가지 권한 예시 모두 응답 본문은 동일합니다.

{
    "message": "401 Unauthorized"
}

요청이 거부되면 같은 토큰으로 현재 사용자 조회 작업에 인증된 요청을 보내 문제를 해결할 수 있습니다. 응답 코드로 다음 정보를 확인할 수 있습니다.

• 200 OK: 토큰이 유효합니다. 원래 요청은 권한 누락과 같은 다른 이유로 거부되었습니다. 엔드포인트에 추가 권한이 필요한지 확인합니다.
• 401 Unauthorized: 토큰이 유효하지 않습니다.
• 403 Forbidden: 토큰은 유효하지만 사용자 계정을 읽는 데 사용할 수 없습니다. 예를 들어 사용자 계정을 읽을 권한이 없는 세분화된 개인 액세스 토큰입니다.

이 확인 방법은 CI/CD job 토큰에는 사용할 수 없습니다.

HTTP 응답 헤더 포함#

HTTP 응답 헤더는 문제 해결 시 추가 정보를 제공할 수 있습니다.

응답에 HTTP 응답 헤더를 포함하려면 --include 옵션을 사용합니다:

curl --request GET \
  --include \
  --url "https://gitlab.example.com/api/v4/projects"
HTTP/2 200
...

HTTP 종료 코드 포함#

API 응답의 HTTP 종료 코드는 문제 해결 시 추가 정보를 제공할 수 있습니다.

HTTP 종료 코드를 포함하려면 --fail 옵션을 포함합니다:

curl --request GET \
  --fail \
  --url "https://gitlab.example.com/api/v4/does-not-exist"
curl: (22) The requested URL returned error: 404

스팸으로 감지된 요청#

REST API 요청이 스팸으로 감지될 수 있습니다. 요청이 스팸으로 감지되고:

• CAPTCHA 서비스가 구성되지 않은 경우 오류 응답이 반환됩니다. 예:

  {"message":{"error":"Your snippet has been recognized as spam and has been discarded."}}
  

• CAPTCHA 서비스가 구성된 경우 다음과 함께 응답을 받습니다:

  • needs_captcha_response가 true로 설정됨.
  • spam_log_id 및 captcha_site_key 필드가 설정됨.

  예:

  {"needs_captcha_response":true,"spam_log_id":42,"captcha_site_key":"REDACTED","message":{"error":"Your snippet has been recognized as spam. Please, change the content or solve the reCAPTCHA to proceed."}}
  

  • 적절한 CAPTCHA API를 사용하여 captcha_site_key로 CAPTCHA 응답 값을 가져옵니다. Google reCAPTCHA v2만 지원됩니다.

  • X-GitLab-Captcha-Response 및 X-GitLab-Spam-Log-Id 헤더를 설정하여 요청을 다시 제출합니다.

    export CAPTCHA_RESPONSE=""
    export SPAM_LOG_ID="<spam_log_id obtained from initial REST response>"
    
    curl --request POST \
      --header "PRIVATE-TOKEN: $PRIVATE_TOKEN" \
      --header "X-GitLab-Captcha-Response: $CAPTCHA_RESPONSE" \
      --header "X-GitLab-Spam-Log-Id: $SPAM_LOG_ID" \
      --url "https://gitlab.example.com/api/v4/snippets?title=Title&file_name=FileName&content=Content&visibility=public"
    

오류: 리버스 프록시를 사용할 때 404 Not Found#

GitLab 인스턴스가 리버스 프록시를 사용하는 경우 GitLab 편집기 확장, GitLab CLI 또는 URL 인코딩된 매개변수가 있는 API 호출을 사용할 때 404 Not Found 오류가 발생할 수 있습니다.

이 문제는 리버스 프록시가 매개변수를 GitLab으로 전달하기 전에 /, ?, @와 같은 문자를 디코딩할 때 발생합니다.

이 문제를 해결하려면 리버스 프록시의 구성을 편집합니다:

• VirtualHost 섹션에서 AllowEncodedSlashes NoDecode를 추가합니다.
• Location 섹션에서 ProxyPass를 편집하고 nocanon 플래그를 추가합니다.

예:

  ServerName git.example.com

  SSLEngine on
  SSLCertificateFile     /etc/letsencrypt/live/git.example.com/fullchain.pem
  SSLCertificateKeyFile  /etc/letsencrypt/live/git.example.com/privkey.pem
  SSLVerifyClient None

  ProxyRequests     Off
  ProxyPreserveHost On
  AllowEncodedSlashes NoDecode

  
     ProxyPass http://127.0.0.1:8080/ nocanon
     ProxyPassReverse http://127.0.0.1:8080/
     Order deny,allow
     Allow from all
  </Location>
</VirtualHost>

server {
  listen       80;
  server_name  gitlab.example.com;
  location / {
     proxy_pass    http://ip:port;
     proxy_set_header        X-Forwarded-Proto $scheme;
     proxy_set_header        Host              $http_host;
     proxy_set_header        X-Real-IP         $remote_addr;
     proxy_set_header        X-Forwarded-For   $proxy_add_x_forwarded_for;
     proxy_read_timeout    300;
     proxy_connect_timeout 300;
  }
}

자세한 내용은 이슈 18775를 참조합니다.

지원 지식베이스#

여전히 문제가 있는 경우 GitLab 지원 지식베이스를 참조합니다.