Skip to content

fix(core): map missing inputs, timeouts and non-JSON responses to 4xx/5xx - #7751

Open
artcashin wants to merge 4 commits into
openbq-org:developfrom
artcashin:fix/core-exception-status-codes
Open

artcashin wants to merge 4 commits into
openbq-org:developfrom
artcashin:fix/core-exception-status-codes

Conversation

@artcashin

@artcashin artcashin commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Problem

ExceptionHandlers.exception gives REST clients the wrong status in three cases:

  • A missing provider input is a 500. When a provider's required QueryParams field is absent from the request, validation passes the ValidationError on to exception. That handler reads error.errors without calling it. For a pydantic ValidationError that is a bound method, not a list, so its "missing" branch never runs and the client gets 500 Unexpected Error -> ValidationError.
  • An upstream timeout is a 500: Unexpected Error -> TimeoutError.
  • An upstream body that is not JSON is a 422. json.JSONDecodeError is a ValueError, so it takes the ValueError branch and the client is told its own request was invalid, when the upstream sent HTML or an empty body.

The Exception catch-all also runs in Starlette's ServerErrorMiddleware, outside CORSMiddleware, so its responses carry no CORS headers. A browser client sees a CORS failure instead of the status.

Change

  • Missing inputs. validation already answers a FastAPI-style 422 for a QueryParams error whose fields are in the request's query. A missing field cannot be in the query, so it fell through to exception. validation now leaves "missing" errors out of that check, so the body is the list it already returns: loc: ["query", "code"], no url, every missing field reported. It also accepts any QueryParams subclass, whatever its name. A provider Data model failing on an upstream response stays a 500. The detail goes through jsonable_encoder, because the error's input can hold dates that JSONResponse cannot serialize. exception is unchanged for this case.
  • Timeouts map to 504: the builtin TimeoutError, asyncio.TimeoutError (its own class on Python 3.10) and requests.Timeout (an OSError). The detail is the error's message or "The upstream data source did not respond in time."; a requests timeout always gets the generic sentence, because its message can carry the request URL.
  • Non-JSON responses map to 502: json.JSONDecodeError, requests.exceptions.JSONDecodeError and aiohttp's ContentTypeError, which is what response.json() raises for a blocked page served as text/html. The detail is "The data source returned a response that is not valid JSON."
  • AppLoader.add_exception_handlers registers each of these types by type. Handlers registered by type run inside the CORS middleware, so these responses keep their CORS headers.

Tests

In tests/api/test_exception_handlers.py:

  • two missing QueryParams fields, with a date in the input, give a 422 list with loc: ["query", ...] for both and no url;
  • a missing field on a QueryParams subclass whose name lacks "QueryParams" gives the same 422;
  • a missing Data field stays a 500;
  • six timeout cases give a 504 (TimeoutError with and without a message, asyncio.TimeoutError, aiohttp.ServerTimeoutError, requests ConnectTimeout and ReadTimeout);
  • three non-JSON cases give a 502 (json and requests JSONDecodeError, aiohttp ContentTypeError).

In tests/api/test_app_loader.py: behind CORSMiddleware, the 504 and 502 responses carry access-control-allow-origin (four cases).

The two files pass 35/35 on Python 3.12 and on 3.10.22. On 3.10 the asyncio.TimeoutError and aiohttp.ServerTimeoutError cases fail without the explicit entry. openbb_platform/core/tests passes 2,260 with 36 skipped (Python 3.12); one test fails, tests/app/test_version.py::test_is_git_repo_true_for_repo_root, because the test container mounts only core/.

Results from a deployment

OpenBQ's Docker image has run these two files as a build-time patch over openbb-core 2.0.1, which matches develop for both files.

  • Missing inputs. In a sweep that called every widget, 82 provider-required inputs answered 500 Unexpected Error -> ValidationError, out of 100 500s for that class of request. With the deployed patch, a request without a required provider input answers 422 (this PR now returns it as a list with loc: ["query", "code"]). We checked this on /cftc/cot, with start_date in the request so the error's input holds a date.
  • Timeouts. EIA requests that timed out upstream answered 500 Unexpected Error -> TimeoutError. They now answer 504.
  • Non-JSON responses. Nasdaq endpoints that returned a non-JSON page answered 422. They now answer 502.
  • The overlay's own tests. Our test module for these core patches runs against the full installed app. It checks the 422, 504 and 502 statuses and their CORS headers through the real rest_api app. It passes 11/11; on unpatched 2.0.1 it had 7 failures and 1 error. The module also covers fix(core): mark required provider-only query params required in the widget #7752 and feat(core): optional per-provider deadline for commands #7753.

Not included

🤖 Generated with Claude Code

…/5xx

ExceptionHandlers.exception read `error.errors` without calling it. For a
pydantic ValidationError that is a bound method, not a list, so a required
provider QueryParams field missing from the request fell through to
"500 Unexpected Error -> ValidationError". It now calls errors(); only a
missing QueryParams field is a 422, so a provider Data model failing on an
upstream response that dropped a key stays a 500. The detail goes through
jsonable_encoder, because the error input can hold dates.

TimeoutError now maps to 504 and json.JSONDecodeError (an upstream that
answered with HTML or an empty body) to 502, each with a clear detail.
AppLoader registers both by type: the Exception catch-all runs outside the
CORS middleware, so its responses carry no CORS headers and a browser sees
a CORS failure instead of the status.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
artcashin and others added 2 commits October 9, 2026 19:45
…t input

Provider extensions name query models freely (e.g. BalanceQuery), so the
title check alone left their missing inputs at 500.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@dlee-bq dlee-bq left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @artcashin, thanks for the PR. This is good for the most part, but there's some handling needing further consideration:

  • requests.Timeout isn’t a subclass of TimeoutError, and Nasdaq and others use requests, so those timeouts are still 500s.
  • When amake_request gets a blocked page served as text/html, aiohttp raises ContentTypeError, not JSONDecodeError. That is probably the most common “non-JSON upstream” case, and it isn’t covered.
  • Python 3.10: core declares >=3.10, but on 3.10 asyncio.TimeoutError is not the builtin TimeoutError. aiohttp timeouts would stay 500 there.
  • The 422 body has a different shape: a single dict, with loc: ["code"] and pydantic’s url. FastAPI’s own 422s, and the existing validation path, return a list with loc: ["query", ...]. Clients that parse FastAPI-style 422s will see the difference, and only the first missing field is reported.

Do we need to register additional handling in the Python Interface's Exception Handlers?

… FastAPI-style 422

Review follow-up:
- requests.Timeout (an OSError) and asyncio.TimeoutError (its own class on
  Python 3.10) map to 504 alongside the builtin TimeoutError.
- aiohttp ContentTypeError, raised when a JSON response arrives as text/html,
  maps to 502 alongside JSONDecodeError.
- A missing QueryParams field is handled by the existing validation path, so
  the 422 detail is a list with loc ["query", ...], without the pydantic url,
  and reports every missing field. The single-dict branch in `exception` is
  back to what develop has.
- All of these types are registered by type, so they keep CORS headers.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@artcashin

Copy link
Copy Markdown
Contributor Author

Thanks, @dlee-bq, and apologies for the slow turnaround. All four points are addressed in ea3edec.

  • requests.Timeout maps to 504. Its message can carry the request URL (Max retries exceeded with url: ...), so the detail is the generic sentence, not str(error).
  • aiohttp ContentTypeError maps to 502, with the same detail as JSONDecodeError. requests.exceptions.JSONDecodeError is listed too: with simplejson installed it is not a json.JSONDecodeError.
  • Python 3.10. asyncio.TimeoutError is listed explicitly. I ran the two test files on 3.10.22: against the previous commit's handlers the asyncio.TimeoutError and aiohttp.ServerTimeoutError cases fail, and with this commit all 35 pass.
  • 422 shape. My single-dict branch is gone. A missing QueryParams field now goes through the existing validation path. That path skipped it only because a missing field cannot be in the request's query. The body is therefore the list that path already returns: loc: ["query", "code"], no url, every missing field reported. exception's "missing" branch is back to what develop has. The detail goes through jsonable_encoder, because pydantic's input for a missing field is the whole input and can hold dates.

Every one of these types is registered by type in add_exception_handlers, so the responses keep their CORS headers. The CORS test now covers requests.ReadTimeout and ContentTypeError as well.

Python interface. I don't think it needs anything. exception_handler in app/static/utils/decorators.py handles a ValidationError itself and lists every error as [Arg] code -> input: ... -> Field required, so a missing provider input is already reported in full. Timeouts and non-JSON responses reach its Exception branch and are re-raised as OpenBBError("[Unexpected Error] -> ReadTimeout -> ..."). There is no status code to get wrong there, and the class name says what happened. The one rough edge is a bare TimeoutError(), which prints an empty message. If you want a friendlier message, I can move the two tuples (TIMEOUT_ERRORS, NON_JSON_ERRORS) to a module both sides import and use them in the decorator.

Not covered: concurrent.futures.TimeoutError, which is also its own class on 3.10. I found nothing in core that raises it to a handler.

Tests: the two files pass 35/35 on Python 3.12 and 3.10. openbb_platform/core/tests passes 2,260 with 36 skipped on 3.12; the one failure is test_version::test_is_git_repo_true_for_repo_root, because my container mounts only core/. The description is updated.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants