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:

{
  "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?