fix(client): use HTTP reason for bodyless error responses - #3467

Changes

Fixes #3461

Problem

A failed HEAD request has no response body by HTTP semantics. For example:

try:
    project.files.head("nonexistent.yaml", ref="main")
except gitlab.exceptions.GitlabHeadError as exc:
    print(exc.response_code)  # 404
    print(repr(exc.error_message))  # ''
    print(str(exc))  # '404: '

This makes logs and CLI output show an empty error message even though the HTTP status has a standard reason phrase.

Root cause

Gitlab.http_request() initializes error_message from result.content and then tries to replace it with the JSON message/error field. For a bodyless HEAD error, result.content is b"" and result.json() raises ValueError, so both attempts leave the message empty. GitlabError then decodes that empty value and GitlabError.__str__() renders "<status>: ".

The specialized GitlabHeadError raised by ProjectFileManager.head() receives the same empty message through on_http_error.

Solution

When no error message was parsed from the response, fall back to:

1. the response's HTTP reason phrase, when the server provided one; or
2. the standard phrase for the status code from http.HTTPStatus.

The change is limited to error-message construction:

• response_code is unchanged;
• response_body remains exactly what the server returned (including b"" for HEAD);
• existing JSON message/error values still take precedence;
• request sending, retries, and redirect handling are unchanged.

Validation

Added regression coverage for:

• a bodyless HEAD error at the Gitlab.http_request() / http_head() level;
• the reported project.files.head() path, including GitlabHeadError and str(exc);
• a JSON error body still taking precedence over the HTTP reason phrase;
• an unknown status code still raising the original GitlabHttpError instead of a fallback lookup error.

Local verification on Python 3.13:

• pytest -q tests/unit/test_gitlab_http_methods.py tests/unit/objects/test_repositories.py — 65 passed
• pytest -q tests/unit — 726 passed, 3 skipped
• tox -e black -- --check — passed
• tox -e isort -- --check-only --diff — passed
• tox -e flake8 — passed
• tox -e mypy — passed
• tox -e pylint — passed (10.00/10)
• cz check --rev-range HEAD~1..HEAD — passed

A standalone reproduction of the issue now reports error_message='Not Found' and str(exc)='404: Not Found', with response_body=b''.

Functional tests were not run because they require a Dockerized GitLab instance; the regression is covered by mocked HTTP unit tests matching the issue's reproduction.

Impact

Small, backward-compatible error-reporting improvement. The only visible behavior change is that empty error messages for bodyless failed responses now include an HTTP reason phrase instead of trailing whitespace.

Documentation and testing

• Documentation update is not required for this internal error-reporting fix
• Unit tests added for the low-level HTTP path, the reported project.files.head() path, and JSON-message precedence