HR API Reference

This reference covers the exception code system used by all Microtec ERP services, with special focus on HR-specific business rule violations.

---

Response Envelope

All API responses follow a standard envelope:

{
  "success": true,
  "data": { },
  "message": null,
  "messageCode": 0,
  "validationErrors": []
}

On error:

{
  "success": false,
  "data": null,
  "message": "Employee already has an active contract",
  "messageCode": 9017,
  "validationErrors": []
}

FluentValidation errors (code 4001)

When messageCode is 4001, check the validationErrors array for field-level messages:

{
  "validationErrors": [
    { "field": "StartDate", "message": "Start date is required" }
  ]
}

---

Code Ranges

Range	Category
1000–1999	CRM Integration Errors
3000–3999	General Business Logic Errors
4000–4999	Validation Errors
5000–5999	System Errors
6000–6999	Authentication & Authorization Errors
7000–7999	Deletion Errors
8000–8999	Balance / Financial Errors
9000–9999	Business Rule Violations

---

CRM Integration Errors (1000–1999)

Code	Name	Description
1001	CrmConnectionFailed	Failed to connect to CRM system
1002	CrmOperationFailed	CRM operation failed

---

General Business Logic Errors (3000–3999)

Code	Name	Description
3001	NotFound	The requested resource was not found
3002	CaptchaNotValid	Captcha validation failed
3003	CaptchaGenerationError	Error generating captcha
3004	QrGenerationError	Error generating QR code
3005	AlreadyExist	Resource already exists (duplicate entry)
3006	InvalidData	The provided data is invalid
3007	IdentityCreationFaild	Failed to create user identity
3008	InvalidOperation	The requested operation is invalid

---

Validation Errors (4000–4999)

Code	Name	Description
4001	FluentValidation	FluentValidation failed — check validationErrors array
4002	ModelStateValidation	Model state validation failed
4003	XssViolation	Cross-site scripting (XSS) violation detected

---

System Errors (5000–5999)

Code	Name	Description
5001	Unhandled	An unhandled exception occurred
5003	Unhealthy	System is unhealthy or unavailable

---

Authentication & Authorization Errors (6000–6999)

Code	Name	Description
6000	Unauthorized	User is not authenticated (HTTP 401)
6001	Forbidden	User is authenticated but not authorized (HTTP 403)
6002	InvalidCredentials	Invalid username or password
6003	DisabledRoute	The requested route is disabled

---

Deletion Errors (7000–7999)

Code	Name	Description
7000	DeleteFailed	Delete blocked — resource has dependencies

---

Balance / Financial Errors (8000–8999)

Code	Name	Description
8000	InvalidBalance	Invalid balance calculation or amount

---

Business Rule Violations (9000–9999)

Sequence & Configuration (9000–9004)

Code	Name	Description
9000	NoSequenceConfiguration	No sequence configuration found for this document type
9001	MaxSequenceReached	Maximum sequence number has been reached
9002	CostIsZero	Cost cannot be zero
9003	PostedStatusRequired	Record must be in posted status to perform this action
9004	SequenceExist	Sequence configuration already exists

Entity Relationships (9005–9008)

Code	Name	Description
9005	JobRelatedWithPositions	Cannot delete job — it is linked to one or more positions
9006	DepartmentRelatedWithEmployees	Cannot delete department — it has employees assigned
9007	DepartmentRelatedWithAnotherDepartment	Cannot delete department — it is a parent of another department
9008	WorklocationRelatedWithPositions	Cannot delete work location — it is linked to positions

Contract Rules (9009–9018)

Code	Name	Description
9009	ContractShouldHavePosition	Contract must have a position assigned
9010	ContractShouldHaveSalary	Contract must have a salary configuration
9011	CantRenewDraftedContract	Cannot renew a contract in draft status
9012	CantUpgradeDraftedContract	Cannot upgrade a contract in draft status
9013	LastRecordEndDateExceedsContractEndDate	Last record's end date exceeds the contract end date
9014	StartDateCannotBeBeforeContractStartDate	Start date cannot be before the contract start date
9015	StartDateCannotBeAfterContractEndDate	Start date cannot be after the contract end date
9016	SalaryOrPositionShouldHaveValue	Either salary or position must have a value
9017	EmployeeAlreadyHasContract	Employee already has an active contract
9018	DraftedContractOnlyCanEdit	Only drafted contracts can be edited

Salary & Template Rules (9019–9021)

Code	Name	Description
9019	SalaryTemplateRelatedWithContracts	Cannot delete salary template — it is linked to contracts
9020	InvalidCalculationFormula	The salary calculation formula is invalid
9021	SalaryItemRelatedWithSalaryTemplateItem	Cannot delete salary item — it is linked to salary template items

Employee Rules (9022–9023)

Code	Name	Description
9022	EmoployeeShouldReportToAnotherEmployee	Employee must report to another employee (note: typo intentional in codebase)
9023	EmployeeHasnotContract	Employee does not have a contract

Record Status Rules (9024–9027)

Code	Name	Description
9024	CantEditOrDeletePostedRecord	Cannot edit or delete a posted record
9025	LoanAmountExceedsLimit	Loan amount exceeds the allowed limit
9026	InstallmentAmountExceedsSalary	Instalment amount exceeds the employee's salary
9027	RecordPostedBefore	Record was already posted previously

Dependency & Workflow Rules (9028–9030)

Code	Name	Description
9028	TheNewItemDependOnAnotherItemYouDontSelectedYet	New item depends on another item that has not been selected yet
9029	EmploymentCommencementPosted	Employment commencement has already been posted
9030	CantRenewClosedNotRenewableContract	Cannot renew a contract that is closed and not renewable

---

TypeScript Enum

Copy this enum into your Angular / TypeScript project for type-safe error handling:

export enum ExceptionCodes {
  // CRM Integration Errors (1000-1999)
  CrmConnectionFailed = 1001,
  CrmOperationFailed = 1002,

  // General Business Logic Errors (3000-3999)
  NotFound = 3001,
  CaptchaNotValid = 3002,
  CaptchaGenerationError = 3003,
  QrGenerationError = 3004,
  AlreadyExist = 3005,
  InvalidData = 3006,
  IdentityCreationFaild = 3007,
  InvalidOperation = 3008,

  // Validation Errors (4000-4999)
  FluentValidation = 4001,
  ModelStateValidation = 4002,
  XssViolation = 4003,

  // System Errors (5000-5999)
  Unhandled = 5001,
  Unhealthy = 5003,

  // Authentication & Authorization Errors (6000-6999)
  Unauthorized = 6000,
  Forbidden = 6001,
  InvalidCredentials = 6002,
  DisabledRoute = 6003,

  // Deletion Errors (7000-7999)
  DeleteFailed = 7000,

  // Balance/Financial Errors (8000-8999)
  InvalidBalance = 8000,

  // Business Rule Violations (9000-9999)
  // Sequence & Configuration
  NoSequenceConfiguration = 9000,
  MaxSequenceReached = 9001,
  CostIsZero = 9002,
  PostedStatusRequired = 9003,
  SequenceExist = 9004,

  // Entity Relationships
  JobRelatedWithPositions = 9005,
  DepartmentRelatedWithEmployees = 9006,
  DepartmentRelatedWithAnotherDepartment = 9007,
  WorklocationRelatedWithPositions = 9008,

  // Contract Rules
  ContractShouldHavePosition = 9009,
  ContractShouldHaveSalary = 9010,
  CantRenewDraftedContract = 9011,
  CantUpgradeDraftedContract = 9012,
  LastRecordEndDateExceedsContractEndDate = 9013,
  StartDateCannotBeBeforeContractStartDate = 9014,
  StartDateCannotBeAfterContractEndDate = 9015,
  SalaryOrPositionShouldHaveValue = 9016,
  EmployeeAlreadyHasContract = 9017,
  DraftedContractOnlyCanEdit = 9018,

  // Salary & Template Rules
  SalaryTemplateRelatedWithContracts = 9019,
  InvalidCalculationFormula = 9020,
  SalaryItemRelatedWithSalaryTemplateItem = 9021,

  // Employee Rules
  EmoployeeShouldReportToAnotherEmployee = 9022,
  EmployeeHasnotContract = 9023,

  // Record Status Rules
  CantEditOrDeletePostedRecord = 9024,
  LoanAmountExceedsLimit = 9025,
  InstallmentAmountExceedsSalary = 9026,
  RecordPostedBefore = 9027,

  // Dependency & Workflow Rules
  TheNewItemDependOnAnotherItemYouDontSelectedYet = 9028,
  EmploymentCommencementPosted = 9029,
  CantRenewClosedNotRenewableContract = 9030,
}

Usage Example

import { ExceptionCodes } from './enums/ExceptionCodes';

function handleApiError(error: ApiError): void {
  switch (error.messageCode) {
    case ExceptionCodes.NotFound:
      showError('The requested item was not found');
      break;

    case ExceptionCodes.EmployeeAlreadyHasContract:
      showError('This employee already has an active contract');
      break;

    case ExceptionCodes.FluentValidation:
      // Field-level validation — display individual field errors
      error.validationErrors?.forEach(ve => {
        setFieldError(ve.field, ve.message);
      });
      break;

    case ExceptionCodes.DeleteFailed:
      showError('Cannot delete — this record has dependencies');
      break;

    default:
      showError(error.message ?? 'An unexpected error occurred');
  }
}

---

Notes

• Code 9022 (EmoployeeShouldReportToAnotherEmployee) contains a typo (Emoylee) that is intentional — it matches the server-side constant exactly. Do not correct it in the enum.
• Codes 6000–6001 correspond to HTTP 401/403 respectively, but provide more specific context for UI messaging.
• Codes 9000–9030 always require user action or data correction; they should never be silently swallowed.