Repository navigation
API: return descriptive error bodies for filter/validation errors #6467
Description
Context
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).
Activity
geovannewashington commentedon Sep 8, 2026
Half of this is already done. #6916 (closing #6915, merged 18 Aug) added the JSON error envelope and the
apiError.yamlschema, so both acceptance criteria here were already met before I started.What was left is the wording. Filter rejections arrived in the envelope but said
"is not valid"or"cannot be decoded"for nine different mistakes, and cloud's list routes answered a bare 400 with no body at all. That is what the linked PR fixes.feat(server): say what was wrong with a rejected filter
feat(server): say what was wrong with a rejected filter
feat(server): say what was wrong with a rejected filter
feat(server): say what was wrong with a rejected filter
feat(server): say what was wrong with a rejected filter
feat(server): say what was wrong with a rejected filter
feat(server): say what was wrong with a rejected filter
feat(server): say what was wrong with a rejected filter
feat(server): say what was wrong with a rejected filter
feat(server): say what was wrong with a rejected filter
feat(server): say what was wrong with a rejected filter
feat(server): say what was wrong with a rejected filter
feat(server): say what was wrong with a rejected filter
feat(server): say what was wrong with a rejected filter