REST API 故障排除

使用 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_site_key 通过适当的 CAPTCHA API 获取 CAPTCHA 响应值。 仅支持 Google reCAPTCHA v2。

  • 重新提交请求，并设置 X-GitLab-Captcha-Response 和 X-GitLab-Spam-Log-Id 头部。

    export CAPTCHA_RESPONSE="<CAPTCHA response obtained from CAPTCHA service>"
    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 标志。

例如：

<VirtualHost *:443>
  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

  <Location />
     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;
  }
}

有关更多信息，请参阅 issue 18775。