sankofa-hw-infra/docs/api-error-format.md

API error response format

All API errors use a consistent JSON body:

{
  "error": "Human-readable message",
  "code": "UNAUTHORIZED",
  "details": {}
}

• error (string): Message for clients and logs.
• code (string, optional): Machine-readable code. One of BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT, INTERNAL_ERROR.
• details (object, optional): Extra data (e.g. validation errors under details when code is BAD_REQUEST).

HTTP status matches the error (400, 401, 403, 404, 409, 500). The OpenAPI spec references the ApiError schema in components.schemas.