docs: add exception reference and error handling guide

[TheSaiEaranti]

Fixes #496

Adds docs/api/exceptions.rst and links it from the API toctree, so the exception hierarchy has one discoverable home.

What's on the page

• The hierarchy — all five classes in redisvl.exceptions, and a note that redis-py exceptions such as redis.exceptions.ConnectionError are not part of it. RedisVL wraps those and chains the original with raise ... from e, so __cause__ still holds it. That seemed like the detail most likely to trip someone writing an except clause.
• A table mapping each exception to the operations that raise it, e.g. SchemaValidationError → load(), RedisSearchError → create() / delete() / search() / aggregate().
• Four try/except examples, including the two the issue asks for.
• Autodoc reference for each class, following the :members: / :show-inheritance: pattern used in schema.rst.

Examples are drawn from real raise sites

Rather than writing plausible-looking snippets, I traced each exception to where it is actually raised so the examples match current behaviour:

Exception	Verified raise site	What the example shows
SchemaValidationError	storage.py _preprocess_and_validate_objects	validate_on_load=True, since validation is off by default and the error cannot otherwise occur
QueryValidationError	index.py _validate_query	ef_runtime on a flat vector field — the concrete case that method rejects
RedisSearchError	create, delete, search, aggregate	wrapping a Redis-side failure
RedisModuleVersionError	_check_svs_support, reached from create()	ordering except clauses, since it subclasses RedisVLError and not RedisSearchError

The from_yaml(..., validate_on_load=True) form matches the example already in the SearchIndex docstring.

Definition of Done

• Exception docs present and discoverable — docs/_build/html/api/exceptions.html renders, all five classes appear with their docstrings, RedisModuleVersionError.for_svs_vamana is documented, and the page is linked from the API index as "Exceptions".
• make docs-build passes — exit 0. The build reports 11 warnings; all 11 are pre-existing and point at query.py / aggregate.py docstrings inherited from redis-py, index.md heading levels, and the MCP how-to cross-references. None reference exceptions.rst.
• Examples align with current exception classes — per the table above.

codespell is clean on both files. No Python changed, so no behaviour change.

Notes

• Docs-only, so this needs the auto:documentation label per CONTRIBUTING. I can't set labels as an outside contributor — could a maintainer add it?
• I deliberately left uv.lock out. Running make docs-build with a recent uv rewrites it to lockfile revision 3 (a ~250 line diff) which has nothing to do with this change.
• If docs: migrate from Sphinx to mkdocs material #608 (Sphinx → mkdocs) lands first, this page is a single autodoc file and cheap to port; happy to do that conversion if you'd prefer to wait for it.

---

Note

Low Risk
Documentation-only change with no runtime or API behavior impact.

Overview
Adds a dedicated Exceptions API page and links it from the API toctree so redisvl.exceptions is easy to find.

The new exceptions.rst documents the five-class hierarchy under RedisVLError, clarifies that redis-py errors are wrapped as RedisSearchError with chaining on __cause__, and includes a table mapping each exception to typical entry points (load(), query(), create(), etc.). It also provides four try/except patterns (schema validation on load, query validation, version vs Redis failures, and catching RedisVLError) plus autoclass reference blocks matching the style used elsewhere in the API docs.

^{Reviewed by Cursor Bugbot for commit 891bfe9. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vishal-bala]

Hi! Thanks for contributing to RedisVL.

This looks good overall — the page is well-organized, and I verified the exception hierarchy, table, and examples against the source without finding inaccuracies.

One thing needs fixing before merge: .. currentmodule:: sits below the prose, so 12 of the 14 :class: references render as plain text instead of links — including all five names in the "When each error is raised" table. It's a one-line move; details inline.

Worth knowing why your Definition of Done didn't catch this: your build report is accurate (I reproduced 11 warnings, none referencing exceptions.rst), but Sphinx only reports unresolved Python cross-references under -n. So make docs-build passing can't detect this class of problem — sphinx -b html -n docs docs/_build/html surfaces it.

Two smaller notes inline, both optional.

[vishal-bala]

This directive needs to be above the prose that uses it. Sphinx resolves bare :class:`RedisVLError` against the current module, and until this line there isn't one — so it looks for a top-level RedisVLError while autodoc registered redisvl.exceptions.RedisVLError. Result: 12 unresolved refs (lines 6, 25, 39, 43, 47, 51, 55, 70, 98, 122).

Moving it to just under the page title fixes all 12 at once, and matches how schema.rst orders it. The autoclass blocks below still work, since currentmodule applies to the rest of the file.

For comparison once fixed: the ~redisvl.index.SearchIndex ref on line 60 already links correctly, because it's fully qualified.

[vishal-bala]

"enough to handle any error the library raises on its own behalf" holds for the operations you document, but argument validation happens in constructors, outside that net. Concretely, with the parameter this page features: VectorQuery(..., ef_runtime=-1) raises ValueError: ef_runtime must be positive, not a RedisVLError — and it fires before the try block in the line 107 example opens. A sentence noting that constructor/argument validation raises standard ValueError would set expectations well.

[vishal-bala]

Minor completeness note: redisvl/mcp/errors.py:22 defines RedisVLMCPError(Exception), which isn't a RedisVLError subclass. Since line 5 reads as exhaustive, either scoping that sentence to the core index/query APIs or adding a pointer would keep this accurate as MCP grows.

[TheSaiEaranti]

Thanks for the thorough review, all three points are in the latest commit.

The currentmodule directive now sits right under the page title, and I removed the duplicate above the autoclass section since it applies to the rest of the file. Verified with the sphinx -n build you suggested: zero unresolved reference warnings for exceptions.rst now. Good to know that make docs-build can't catch this class of problem, I'll use -n for docs changes going forward.

Both optional notes are in too. The intro now scopes the base-class claim to the core index and query APIs with a pointer to redisvl.mcp.errors.RedisVLMCPError, and the note block mentions that constructor validation raises standard ValueError before any try block opens, using your ef_runtime example.