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 APIを使用して、captcha_site_keyで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 editor拡張機能、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を参照してください。