Error Handling Standards

The API follows the RFC 9457 (Problem Details for HTTP APIs) standard to ensure consistent and machine-readable error responses.

Standard Error Response

All error responses (4xx and 5xx) return a JSON body with the following structure:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15",
  "title": "Bad Request",
  "status": 400,
  "detail": "The provided catalog name is already in use.",
  "instance": "/api/v1/catalogs",
  "errors": {
    "Name": ["Name must be unique within the company"]
  }
}

HTTP Status Codes

The system uses standard HTTP status codes to communicate the outcome of a request:

Code	Meaning	Usage
200	OK	Resource retrieved or updated successfully.
201	Created	Resource created successfully.
400	Bad Request	Validation errors or invalid business logic.
401	Unauthorized	Missing or invalid JWT token.
403	Forbidden	User lacks permission for the specific resource.
404	Not Found	The requested resource does not exist.
500	Internal Error	Unexpected server-side exception.

Global Middleware

In the .NET Backend, the ExceptionMiddleware catches all unhandled exceptions and converts them into the standard Problem Details format. This ensures that even unexpected crashes do not leak internal stack traces to the client in production.