> For the complete documentation index, see [llms.txt](https://framework.aic.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://framework.aic.io/technical-guidelines-code-standards-and-tech-stack/asp.net-core-web-api-standards/problemdetails-and-error-responses.md).

# ProblemDetails and Error Responses

## Purpose

Clients need consistent error responses. AIC APIs use ProblemDetails-style responses for predictable machine-readable errors.

## Standard Error Shape

AIC APIs SHOULD return:

```json
{
  "type": "https://docs.aic.example/errors/validation-failed",
  "title": "Validation failed",
  "status": 400,
  "detail": "One or more validation errors occurred.",
  "instance": "/v1/cases",
  "traceId": "00-...",
  "errors": {
    "title": ["Title is required."]
  }
}
```

## Rules

* Do not expose stack traces to clients.
* Do not leak secrets, tokens, connection strings or sensitive data.
* Include correlation or trace identifiers.
* Keep error codes stable.
* Separate user-facing message from internal diagnostic detail.
* Use 409 for concurrency conflicts.
* Use 403 for authenticated access denied.
* Use 404 carefully where resource existence may be sensitive.

## Exception Mapping

| Exception or result             | HTTP status |
| ------------------------------- | ----------: |
| Validation failure              |         400 |
| Unauthorized                    |         401 |
| Forbidden                       |         403 |
| Not found                       |         404 |
| Conflict                        |         409 |
| External dependency unavailable |         503 |
| Unexpected exception            |         500 |

## Logging

Server logs should include details not returned to clients:

* exception type
* message
* stack trace
* user or service identity where permitted
* correlation id
* endpoint
* request id
* dependency call details

## Review Checklist

* Are all expected errors mapped?
* Are validation errors structured?
* Are sensitive details hidden?
* Are trace identifiers included?
* Are errors documented in OpenAPI?