Issue Station
Sign In
Tools hereToolbox

vllm - ✅(Solved) Fix [Bug]: Speech-to-Text endpoint may return 501 but not documented in OpenAPI [1 pull requests, 1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
vllm-project/vllm#38004•Fetched 2026-04-08 01:22:01
View on GitHub
Comments
0
Participants
1
Timeline
9
Reactions
0
Author
Sebastian-dongSebastian-dong
Participants
Sebastian-dongSebastian-dong
Timeline (top)
referenced ×5cross-referenced ×3labeled ×1

The Speech-to-Text (STT) endpoint may return a 501 Not Implemented response when certain handlers are not available. However, this response code does not appear to be documented in the OpenAPI specification.

Error Message

  1. Or convert it into a standardized error response (e.g., 400/404/500)
  • Or standardize exception handling in the router layer

Root Cause

The Speech-to-Text (STT) endpoint may return a 501 Not Implemented response when certain handlers are not available. However, this response code does not appear to be documented in the OpenAPI specification.

Fix Action

Fixed

PR fix notes

PR #38036: Add 501 response to STT endpoint OpenAPI spec

Description (problem / solution / changelog)

Summary

Both /v1/audio/transcriptions and /v1/audio/translations raise NotImplementedError when the handler is None (i.e., the model doesn't support the task). The global exception handler already converts this to a proper 501 JSON response, but the OpenAPI schema didn't document it — meaning auto-generated clients wouldn't expect or handle this case.

Added HTTPStatus.NOT_IMPLEMENTED to the responses dict on both routes so the 501 shows up in the spec.

Fixes #38004

Changed files

  • vllm/entrypoints/openai/speech_to_text/api_router.py (modified, +2/-0)
RAW_BUFFERClick to expand / collapse

Your current environment

<details> <summary>The output of <code>python collect_env.py</code></summary> 
(Not strictly required for this issue since it is a code-level/API contract issue rather than runtime-specific behavior. Can provide if needed.)

### 🐛 Describe the bug

## Description

The Speech-to-Text (STT) endpoint may return a `501 Not Implemented` response when certain handlers are not available. However, this response code does not appear to be documented in the OpenAPI specification.

## Location

vllm/entrypoints/openai/speech_to_text/api_router.py

## Problem

- The route may raise `NotImplementedError` when a feature or backend is not implemented.
- This results in an HTTP 501 response.
- The OpenAPI schema does not document this possible response.

## Expected Behavior

One of the following:

1. Document the 501 response in the OpenAPI schema
2. Or convert it into a standardized error response (e.g., 400/404/500)

## Actual Behavior

- 501 response may be returned implicitly
- Not visible in API documentation

## Minimal Reproduction (Conceptual)

This issue can occur when invoking the STT endpoint with a configuration where the handler is not implemented. In such cases, the router raises `NotImplementedError`, leading to an HTTP 501 response.

(Providing a full runnable script may not be necessary here since the issue is observable from code inspection.)

## Impact

- Breaks API contract consistency
- Client SDKs generated from OpenAPI may not handle this case
- Unexpected behavior for API users

## Proposed Fix

- Add 501 response to OpenAPI spec
- Or standardize exception handling in the router layer

## Notes

Happy to submit a PR after alignment on expected behavior.

### Before submitting a new issue...

- [x] Make sure you already searched for relevant issues, and asked the chatbot living at the bottom right corner of the [documentation page](https://docs.vllm.ai/en/latest/), which can answer lots of frequently asked questions.

extent analysis

Fix Plan

To address the issue, we will standardize exception handling in the router layer to return a consistent error response. We will convert the NotImplementedError into a standardized error response, such as a 500 Internal Server Error.

Step-by-Step Solution

  • Modify the api_router.py file to catch NotImplementedError exceptions and return a standardized error response.
  • Update the OpenAPI schema to document the possible error responses.

Example Code

from fastapi import HTTPException
from fastapi.responses import JSONResponse

# In api_router.py
try:
    # Existing code that may raise NotImplementedError
    handler = get_handler()
    if handler is None:
        raise NotImplementedError("Handler not implemented")
except NotImplementedError as e:
    # Convert to a standardized error response
    raise HTTPException(status_code=500, detail=str(e))

# Alternatively, you can use a custom exception handler
@api_router.exception_handler(NotImplementedError)
async def not_implemented_error_handler(request: Request, exc: NotImplementedError):
    return JSONResponse(status_code=500, content={"error": str(exc)})

Verification

To verify the fix, test the STT endpoint with a configuration where the handler is not implemented. The response should now be a standardized error response (e.g., 500 Internal Server Error) instead of a 501 Not Implemented response.

Extra Tips

  • Make sure to update the API documentation to reflect the changes in error handling.
  • Consider adding logging to track instances of NotImplementedError to help identify areas where implementation is missing.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#API rate limit#retriever error#indexing error#inference speed

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

vllm - ✅(Solved) Fix [Bug]: Speech-to-Text endpoint may return 501 but not documented in OpenAPI [1 pull requests, 1 participants]