Context
Follow-up to #3523 / #6466.
That PR makes malformed filter query params return a consistent 400 instead of a cryptic 500, but the response body stays empty — consistent with the API's current convention, where the central error handler (api/pkg/echo/handlers/errors.go) renders every error as c.NoContent(status) (it even strips echo.HTTPError messages). So clients get a status code but no explanation of what was wrong with the filter.
Proposal
Introduce a standard JSON error envelope (e.g. {"error": "...", "code": "..."}) emitted by the central error handler, so filter/validation failures (and errors generally) carry a human-readable description — e.g. filter is not valid base64, filter exceeds the maximum size, unknown filter operator. The query package already returns classified sentinels (ErrFilterInvalid, ErrFilterTooLarge) and routes/errors has an ErrDataInvalidEntity{Fields} shape to build on.
This is a contract-wide change (touches every endpoint's error responses and the OpenAPI 400/4xx response schemas), which is why it was deferred from #3523 rather than done piecemeal on the filter routes.
Acceptance
- A standard error body schema, documented in OpenAPI (the 400 components currently have no schema).
- Backward-compatible rollout (clients checking status codes unaffected).
Context
Follow-up to #3523 / #6466.
That PR makes malformed
filterquery params return a consistent 400 instead of a cryptic 500, but the response body stays empty — consistent with the API's current convention, where the central error handler (api/pkg/echo/handlers/errors.go) renders every error asc.NoContent(status)(it even stripsecho.HTTPErrormessages). So clients get a status code but no explanation of what was wrong with the filter.Proposal
Introduce a standard JSON error envelope (e.g.
{"error": "...", "code": "..."}) emitted by the central error handler, so filter/validation failures (and errors generally) carry a human-readable description — e.g.filter is not valid base64,filter exceeds the maximum size,unknown filter operator. Thequerypackage already returns classified sentinels (ErrFilterInvalid,ErrFilterTooLarge) androutes/errorshas anErrDataInvalidEntity{Fields}shape to build on.This is a contract-wide change (touches every endpoint's error responses and the OpenAPI 400/4xx response schemas), which is why it was deferred from #3523 rather than done piecemeal on the filter routes.
Acceptance