Standardize API error responses to a single error field
Nobody has claimed this yet.
- Dominant language
- C#
- Stars
- 5
- Forks
- 3
- Avg merge
- 1d 22h
- Merged PRs (30d)
- 14
Description
Background
Follow-up from PR #751 review (thread: https://github.com/sefe/dorc/pull/751#discussion_r3473989924).
Different API endpoints currently return error information in different shapes — a bare JSON string (BadRequest("…")), a DTO with a Message property (e.g. CopyEnvBuildResponseDto), serialized exception objects (StatusCode(500, exception)), and ASP.NET ProblemDetails (title/detail). To cope, the client ApiCaller.ExtractErrorMessage (src/Dorc.Core/ApiCaller.cs) has to probe several candidate fields, which is fragile and easy to get wrong.
Goal
Standardize on a single error contract returned by every API endpoint, so clients read one field.
Proposed scope
- Define one error-response shape (e.g.
{ "error": "…" }, or ASP.NETProblemDetailswith a single agreed field) and document it. - Update controllers to return that shape consistently for 4xx/5xx, and stop returning raw exception objects / stack traces to clients (use a correlation id; log details server-side). This overlaps with a separate security concern about verbose error/stack-trace disclosure across the API (
DefaultExceptionHandlerand several controllers returningStatusCode(500, e)/error + " - " + ex). - Simplify
ApiCaller.ExtractErrorMessageto read the single field once the server side is consistent. - Add/adjust tests.
Notes
- Cross-cutting change touching most controllers — intentionally kept out of PR #751 to keep that PR scoped.
- Once done, the multi-field probing added in #751 can be removed.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with src/Dorc.Core/ApiCaller.cs, DefaultExceptionHandler, and the controllers returning StatusCode(500, e) or mixed error shapes; review the response types such as CopyEnvBuildResponseDto and the discussion from PR #751. Define and document the single agreed error field, update the affected 4xx/5xx responses, remove multi-field probing, and add or adjust tests confirming consistent responses without raw exception details.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp
- Domain
- api, backend-api-design, security
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100