Employee API Response and Error Model

Summary

Direct endpoints use ApiResponse<T> and translate application Result<T> values to HTTP status codes. Compatibility endpoints return plain legacy-shaped JSON and simpler empty or string error bodies. RFC Problem Details is Not implemented for these mappings.

Audience

• Frontend and integration developers
• QA engineers
• Support engineers interpreting safe failures

Reference Content

The following envelope and mapping tables are the confirmed public response reference for direct and compatibility Employee endpoints.

Direct response envelope

{
  "success": true,
  "message": "Success",
  "data": {},
  "correlationId": "safe-correlation-id",
  "errors": null
}

Properties are success, message, data, optional correlationId, and optional errors (a map of string arrays). Validation messages are grouped under validation; missing tenant context uses the tenant key. Consumers should use the HTTP status and success, not parse message text.

Confirmed mapping

Source/result	Direct HTTP	Direct body	Compatibility HTTP/body
Success	200	ApiResponse<T>	200, plain DTO/list/string
Create success	201	ApiResponse<EmployeeResponse> plus Location	200, plain DTO
Not found	404	Failure envelope	404, empty body
Conflict	409	Failure envelope	400, plain error string
Validation	400	Failure envelope with errors.validation	400, plain error string
Missing tenant, direct	400	Failure envelope with errors.tenant	Outcome varies; Requires confirmation
Other handled result	400	Failure envelope	400, plain error string
Unauthorized / forbidden	Requires confirmation	No Employee-specific 401/403 mapping	Requires confirmation
Unhandled error	Requires confirmation	No public Employee-specific contract	Requires confirmation

Examples

Validation failure:

{
  "success": false,
  "message": "Validation failed.",
  "data": null,
  "correlationId": "safe-correlation-id",
  "errors": {"validation": ["Employee name is required."]}
}

Compatibility invalid identifier:

"employee id is not a valid GUID."

The exact message includes the supplied safe identifier. Do not expose submitted personal data in support records.

Source References

• microservices/src/contracts/Common/ApiResponse.cs
• microservices/src/employee-service/Application/Common/Cqrs.cs
• microservices/src/employee-service/Api/EmployeeDirectEndpoints.cs
• microservices/src/employee-service/Api/EmployeeCompatibilityEndpoints.cs

Related Articles

• Authentication and context
• Validation
• Employee troubleshooting

See Also

• Employee management
• Compatibility employees

Keywords

• API response
• Result translation
• Error mapping

Revision Information

• Status: Draft
• Last reviewed: 2026-07-15
• Review cycle: Quarterly