fix(proxy): improve Headroom /v1/compress HTTP 404 diagnostics

[aayush598]

TLDR

Problem this solves:

• /v1/compress HTTP 404 responses provide limited troubleshooting context.
• Common self-hosted deployment issues are difficult to identify from the existing error payload.

How it solves it:

• Adds a troubleshooting hint for /v1/compress HTTP 404 responses.
• Preserves the existing upstream status code and response body.
• Refactors error detail construction into a shared helper.
• Adds regression tests for both 404 and non-404 responses.

Relevant issues

Related to #35933

Linear ticket

N/A

Pre-Submission checklist

Please complete all items before asking a LiteLLM maintainer to review your PR

• I have added meaningful tests
• My PR passes all CI/CD checks (e.g., lint, format, unit tests)
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have received a Greptile Confidence Score of at least 4/5 before requesting a maintainer review (Greptile reviews automatically once the PR is opened; only comment @greptileai to re-request a review after pushing changes)

Screenshots / Proof of Fix

Regression tests added:

• test_apply_guardrail_404_error_includes_troubleshooting_hint
• test_apply_guardrail_non_404_error_omits_troubleshooting_hint

The tests verify:

• HTTP 404 responses preserve the original upstream error details and include a troubleshooting hint.
• Non-404 responses preserve the existing behavior without adding the hint.

The behavior change is limited to the error payload returned for HTTP 404 responses.

Type

🐛 Bug Fix
✅ Test

Changes

• Added _build_compress_failure_detail() to centralize /v1/compress error detail construction.
• Added a troubleshooting hint for HTTP 404 responses.
• Preserved the existing upstream status_code and body for all responses.
• Updated both /v1/compress error paths to use the shared helper.
• Added regression tests covering:
  • HTTP 404 responses include the troubleshooting hint.
  • Non-404 responses remain unchanged.

Final Attestation

• The tests check the right things, including the edge cases, and regressions in the respective real-world customer use-cases are not possible after this PR

[greptile-apps]

Greptile Summary

This PR centralizes Headroom /v1/compress failure-detail construction and adds a troubleshooting hint to upstream 404 responses while preserving existing status and body fields

• Routes both HTTP failure branches through the shared helper
• Adds regression coverage for 404 and non-404 responses

Confidence Score: 4/5

The PR appears safe to merge after addressing the non-blocking mutable dictionary construction

The changed failure paths preserve existing status and body diagnostics, conditionally add the intended 404 hint, and have focused regression coverage; the only accepted concern is a repository coding-convention violation

Files Needing Attention: litellm/proxy/guardrails/guardrail_hooks/headroom/headroom.py

Important Files Changed

Filename	Overview
litellm/proxy/guardrails/guardrail_hooks/headroom/headroom.py	Adds shared 404 diagnostic construction; behavior is consistent across both failure branches, but the helper violates the repository's no-mutation convention
tests/test_litellm/proxy/guardrails/guardrail_hooks/test_headroom.py	Adds focused mocked regression tests confirming that 404 responses include the hint and non-404 responses preserve the prior detail shape

_{Reviews (1): Last reviewed commit: "fix(proxy): improve Headroom 404 compres..." | Re-trigger Greptile}

[greptile-apps]

Avoid mutable detail construction

The helper initializes detail and then mutates it to add the hint, contrary to the repository's functional coding convention. Constructing and returning the appropriate dictionary in each branch avoids unnecessary mutable state.

Suggested change

	detail: dict[str, object] = {"status_code": status_code, "body": body}
	if status_code == 404:
	detail["hint"] = (
	"The Headroom compression endpoint returned HTTP 404. "
	"Verify that the configured Headroom endpoint is correct and that "
	"the compression endpoint is available. If you are using a "
	"self-hosted deployment, some deployments require enabling remote "
	"compression (for example, HEADROOM_COMPRESS_ALLOW_REMOTE=1)."
	)
	return detail
	if status_code == 404:
	return {
	"status_code": status_code,
	"body": body,
	"hint": (
	"The Headroom compression endpoint returned HTTP 404. "
	"Verify that the configured Headroom endpoint is correct and that "
	"the compression endpoint is available. If you are using a "
	"self-hosted deployment, some deployments require enabling remote "
	"compression (for example, HEADROOM_COMPRESS_ALLOW_REMOTE=1)."
	),
	}
	return {"status_code": status_code, "body": body}

Context Used: CLAUDE.md (source)

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[codspeed-hq]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing aayush598:fix/headroom-404-error-diagnostics (29d52cd) with litellm_internal_staging (4b7adab)}

[mateo-berri]

@aayush598 to fix the lint fail, pull latest staging. I've since updated the error message to be more helpful (but, it's kind of a chicken-and-egg problem since you need to pull staging to see the improved error message :P)

[aayush598]

Hi @mateo-berri — rebased onto latest litellm_internal_staging (4b7adab) and applied the Greptile suggestion. All 79 CI checks pass (lint, unit tests, CodSpeed, Veria AI) and Greptile confidence is 4/5. Could you take a look and approve when you get a chance? Thanks!

[ryan-crabbe-berri]

thanks!