From 6ef62af61213f9c768531a724aba7b44f14eef4a Mon Sep 17 00:00:00 2001
From: BillionClaw <267901332+BillionClaw@users.noreply.github.com>
Date: Wed, 25 Mar 2026 06:32:56 +0800
Subject: [PATCH] fix(proxy): return 405 with helpful message for GET
 /responses

When Codex CLI or similar clients attempt to connect via HTTP GET to
/v1/responses or /responses, they receive a generic FastAPI 405
Method Not Allowed error. This is unhelpful since these clients may
not know the endpoint requires WebSocket or POST.

This change adds explicit GET handlers for /responses and /v1/responses
that return a 405 with a descriptive error message explaining:
- POST is supported for creating responses
- WebSocket is supported for streaming mode
- GET is not a valid method for this endpoint

Fixes BerriAI/litellm#24502
---
 .../proxy/response_api_endpoints/endpoints.py | 36 +++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/litellm/proxy/response_api_endpoints/endpoints.py b/litellm/proxy/response_api_endpoints/endpoints.py
index 8023853e263..5fe0c0f4b0b 100644
--- a/litellm/proxy/response_api_endpoints/endpoints.py
+++ b/litellm/proxy/response_api_endpoints/endpoints.py
@@ -935,6 +935,42 @@ async def cancel_response(
         )
 
 
+@router.get(
+    "/v1/responses",
+    dependencies=[Depends(user_api_key_auth)],
+    tags=["responses"],
+)
+@router.get(
+    "/responses",
+    dependencies=[Depends(user_api_key_auth)],
+    tags=["responses"],
+)
+async def get_responses_root(
+    request: Request,
+    user_api_key_dict: UserAPIKeyAuth = Depends(user_api_key_auth),
+):
+    """
+    Handle GET /responses - return a helpful error for clients attempting HTTP GET.
+
+    The Responses API uses WebSocket for streaming mode or POST for creating responses.
+    GET /v1/responses is not a valid OpenAI Responses API endpoint.
+
+    For WebSocket connections, use: ws://host/v1/responses?model=<model>
+    For creating responses, use: POST /v1/responses with a request body
+    """
+    raise HTTPException(
+        status_code=405,
+        detail=(
+            "Method Not Allowed. The Responses API at /v1/responses supports:\n"
+            "  - POST: Create a new response (send a request body)\n"
+            "  - WebSocket: Connect to ws://host/v1/responses?model=<model> for streaming mode\n"
+            "GET requests are not supported. If you are using a Codex CLI or similar client "
+            "that connects via WebSocket, ensure the model query parameter is provided."
+        ),
+        headers={"Allow": "POST, WebSocket"},
+    )
+
+
 @router.websocket("/v1/responses")
 @router.websocket("/responses")
 async def responses_websocket_endpoint(