Problem Statement
Filter and storage operations can fail for very different reasons: client input
can be invalid, MDBX can return a storage error, or persisted data can be
corrupt. Previously, some of these failures were silently skipped or collapsed
into generic false/null results. API users receive vague failures, and operators
lose the detail needed to debug production issues.
This affects users of search, insert, delete-vector, delete-by-filter, and
update-filter routes because a validation problem can look like a missing index
or generic server failure.
Proposed Solution
Introduce a structured operation result contract for filter/storage paths and
map it consistently at the HTTP boundary:
- success returns the expected value;
- caller-fixable validation failures return HTTP 400;
- MDBX/storage/corruption/internal failures return HTTP 500;
- route logs include the affected route/index context;
- client responses include the relevant error message.
Alternatives Considered
Keep using exceptions for all failures. This keeps signatures smaller, but makes
it harder to distinguish validation errors from internal failures at the API
boundary without parsing exception strings.
Keep returning bool / std::optional and logging details internally. This is
simple for callers but loses structured failure information and encourages
generic API responses.
Problem Statement
Filter and storage operations can fail for very different reasons: client input
can be invalid, MDBX can return a storage error, or persisted data can be
corrupt. Previously, some of these failures were silently skipped or collapsed
into generic false/null results. API users receive vague failures, and operators
lose the detail needed to debug production issues.
This affects users of search, insert, delete-vector, delete-by-filter, and
update-filter routes because a validation problem can look like a missing index
or generic server failure.
Proposed Solution
Introduce a structured operation result contract for filter/storage paths and
map it consistently at the HTTP boundary:
Alternatives Considered
Keep using exceptions for all failures. This keeps signatures smaller, but makes
it harder to distinguish validation errors from internal failures at the API
boundary without parsing exception strings.
Keep returning
bool/std::optionaland logging details internally. This issimple for callers but loses structured failure information and encourages
generic API responses.