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>",
                ...
            ],
        }
    }
}

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 지원 지식베이스를 참조하세요.