/join endpoint returns HTTP 200 with error payload instead of proper HTTP error status codes

[NeilMazumdar]

Checked other resources

• This is a bug, not a usage question. For questions, please use the LangChain Forum (https://forum.langchain.com/).
• I added a clear and detailed title that summarizes the issue.
• I read what a minimal reproducible example is (https://stackoverflow.com/help/minimal-reproducible-example).
• I included a self-contained, minimal example that demonstrates the issue INCLUDING all the relevant imports. The code run AS IS to reproduce the issue.

Example Code

import requests
import json

# Test case: Request with invalid thread ID and run ID
# This should return HTTP 404, but instead returns HTTP 200 with error in payload
url = "https://{base_url}/threads/{invalid-thread-id}/runs/{invalid-run-id}/join"

response = requests.get(url)
print(f"Status Code: {response.status_code}")
print(f"Response: {response.text}")

# Expected: HTTP 404 status code
# Actual: HTTP 200 with error payload

Error Message and Stack Trace (if applicable)

Status Code: 200
Response: {"__error__":{"error":"HTTPException","message":"404: Run with ID 'invalid-run-id'
not found. Please verify the ID is correct and the run hasn't been deleted or expired."}}

Description

• I'm trying to use the LangGraph /threads/{threadId}/runs/{runId}/join endpoint to retrieve
  run results.
• I expect that when a run ID or thread ID doesn't exist, the API should return an HTTP 404
  status code (or other appropriate 4xx error code).
• Instead, the API returns HTTP 200 (success) with error information embedded in the JSON
  response payload under an error field.

Current Behavior:

• /threads/{threadId}/runs/{runId}/join endpoint returns HTTP 200 status code
• Error information is included in JSON response: {"error": {"error": "HTTPException",
  "message": "404: Run with ID '...' not found..."}}

Expected Behavior:

• Should return HTTP 404 status code for not found errors
• Error details can still be in response body, but HTTP status should reflect the error
  condition

Impact:
This makes it difficult for client applications to properly handle errors using standard HTTP
status code checking. Clients expecting HTTP error codes need to parse the JSON response to
detect error conditions, which breaks standard REST API conventions.

Note: The regular /threads/{threadId}/runs/{runId} endpoint (without /join) correctly returns
HTTP 404 for the same invalid IDs, so this appears to be specific to the /join endpoint.

System Info

This issue was observed with a deployed self-hosted and local langgraph dev LangGraph server endpoint.
The inconsistent behavior is between:

• /threads/{threadId}/runs/{runId} (returns proper HTTP 404)
• /threads/{threadId}/runs/{runId}/join (returns HTTP 200 with error payload)

[QuangNguyen2609]

same issue

[SunHuawei]

The issue is in the server-side code (langgraph-api package), specifically in the join_run() and join_run_stream() functions in api/runs.py.

These functions return a StreamingResponse with HTTP 200 before validating if the run exists. When an error occurs, it's wrapped in {"__error__": {...}} within the response body, but the HTTP status remains 200.

To fix it, we can simply add a database check before creating the StreamingResponse:

--- a/api/runs.py
+++ b/api/runs.py
@@ -453,6 +453,18 @@ async def join_run(request: ApiRequest):
     validate_uuid(thread_id, "Invalid thread ID: must be a UUID")
     validate_uuid(run_id, "Invalid run ID: must be a UUID")
 
+    # Check if run exists before starting streaming response
+    # This ensures proper HTTP 404 status code instead of HTTP 200 with __error__
+    async with connect() as conn:
+        run = await fetchone(
+            conn,
+            "SELECT run_id FROM runs WHERE run_id = $1 AND thread_id = $2",
+            (run_id, thread_id),
+        )
+        if not run:
+            raise HTTPException(
+                status_code=404,
+                detail=f"Run with ID '{run_id}' not found. Please verify the ID is correct and the run hasn't been deleted or expired."
+            )
+
     # A touch redundant, but to meet the existing signature of join, we need to throw any 404s before we enter the streaming body
     await Runs.Stream.check_run_stream_auth(run_id, thread_id)
     sub = await Runs.Stream.subscribe(run_id, thread_id)
@@ -480,6 +492,18 @@ async def join_run_stream(request: ApiRequest):
     validate_uuid(thread_id, "Invalid thread ID: must be a UUID")
     validate_uuid(run_id, "Invalid run ID: must be a UUID")
 
+    # Check if run exists before starting streaming response
+    # This ensures proper HTTP 404 status code instead of HTTP 200 with __error__
+    async with connect() as conn:
+        run = await fetchone(
+            conn,
+            "SELECT run_id FROM runs WHERE run_id = $1 AND thread_id = $2",
+            (run_id, thread_id),
+        )
+        if not run:
+            raise HTTPException(
+                status_code=404,
+                detail=f"Run with ID '{run_id}' not found. Please verify the ID is correct and the run hasn't been deleted or expired."
+            )
+
     last_event_id = request.headers.get("Last-Event-ID")
     if last_event_id and not plus_features_enabled():
         raise HTTPException(

The langgraph-api package is available on PyPI, but I couldn't locate its source repository. I'd like to submit a PR if anyone can point me the correct location.