Skip to main content

API Error Handling

Summary​

Native Recruitment maps application result kinds to four verified client-facing status families. Monolith controllers return MVC error results directly. Tenant absence has dedicated host middleware, while remote Employee Service and unexpected persistence failures lack lifecycle-specific mapping.

Audience​

Developers, QA, support, and solution architects.

Reference Content​

Error behavior is catalogued by verified HTTP status family and implementation boundary.

Verified status patterns​

Status familyVerified source and use
SuccessNative DTOs, compatibility objects, HR Operations entities/lists, Employee envelopes
CreatedEmployee Service create only within the lifecycle handoff
Bad requestNative validation/default result; tenant absence; monolith input/state checks
UnauthorizedAuthentication middleware for protected monolith controllers/actions
ForbiddenMonolith access, permission, role, ownership, or visibility denial
Not foundMissing offer, onboarding, candidate, exit, or public link
ConflictNative terminal-state/idempotency conflicts and Employee create duplicate

Native result mapping​

Application NotFound maps to a not-found object containing a message. Conflict maps to a conflict message. Validation and unknown application error kinds map to bad request. Success normally maps to a direct DTO. The mapper does not define Unauthorized, Forbidden, or Created for Recruitment lifecycle commands.

Monolith error bodies​

Controller errors are inconsistent by action: some return plain strings, some empty not-found/forbidden results, and framework authentication produces its standard challenge behavior. [ApiController] can reject binding/model-state failures before action execution.

Downstream failures​

Recruitment's Employee client explicitly handles create conflict by searching for the existing employee. Other unsuccessful responses use standard HTTP exception behavior. No inspected lifecycle exception middleware converts these failures to a stable error contract, so an internal server error is possible.

Client behavior​

The portal reads several possible error-message shapes and provides fallback text. A response indicating unauthorized clears or redirects the portal session. This does not establish a backend error contract.

Requires confirmation​

  • Standard error schema, correlation data, and safe detail policy.
  • Mapping for downstream timeout, unavailability, malformed response, and partial success.
  • Whether conflict or bad request is canonical for terminal lifecycle transitions.
  • Compatibility parity for status codes and bodies.

Source References​

  • microservices/src/recruitment-service/Api/EndpointResults.cs
  • microservices/src/recruitment-service/Program.cs
  • microservices/src/recruitment-service/Infrastructure/EmployeeServiceClient.cs
  • microservices/src/employee-service/Api/EmployeeDirectEndpoints.cs
  • Controllers/RecruitmentController.cs
  • Controllers/HrOperationsController.cs
  • UI/salary-ui/packages/api-client/src/axiosConfig.ts
  • UI/salary-ui/apps/client-hrms-portal/src/pages/hr/RecruitmentOnboardingPage.tsx
  • UI/salary-ui/apps/client-hrms-portal/src/pages/hr/HrOperationsPage.tsx

See Also​

Keywords​

  • Error mapping
  • Downstream failure
  • Compatibility error parity

Revision Information​

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