Payroll API Response and Error Model

Summary

Native, compatibility, file, and foundation operations use different response conventions; there is no universal Payroll response envelope or RFC Problem Details contract.

Audience

Frontend and backend developers, QA and support engineers, architects, security reviewers, and implementation partners.

Reference Content

Outcome	Native run/output behavior	Compatibility behavior
Success	Usually 200 with plain DTO/array; file endpoints return attachment bytes	200 with bare object, array, file, or raw string
Invalid period/request	Calculation maps 400 {message}	Guarded operations map 400 raw text
Not found	Selected operations map 404, sometimes empty and sometimes {message}	Selected operations map 404 empty or raw text
Invalid lifecycle/conflict	Native calculation/output commands map 409 {message}	Guarded lifecycle operations generally map 400 raw text
Missing Attendance	Employee is skipped during calculation; no dedicated HTTP error	Same native engine behavior when invoked
Recovery failure	Freeze maps 409	Guarded compatibility operations map 400
Payslip/export ineligible	Native frozen-only operations map 409	Compatibility frozen lookup generally maps 404 raw text
Missing tenant	No consistent mapped response confirmed	No consistent mapped response confirmed
Unauthorized/forbidden	Deployment-level behavior Requires confirmation	Deployment-level behavior Requires confirmation
External dependency/unhandled failure	Framework-level response; public body not specified	Framework-level response; public body not specified

Only the root service-information operation uses ApiResponse<ServiceInfoResponse>. The API does not configure Problem Details as its contract. Error text is implementation-facing and clients should branch on confirmed status codes rather than parse message wording.

Source References

• microservices/src/payroll-service/Api/PayrollRunEndpoints.cs
• microservices/src/payroll-service/Api/PayrollOutputEndpoints.cs
• microservices/src/payroll-service/Api/PayrollCompatEndpoints.cs
• microservices/src/payroll-service/Program.cs
• microservices/src/shared-kernel/Extensions/EndpointRouteBuilderExtensions.cs

Related Articles

• Payroll API
• Payroll technical documentation

See Also

• Payroll business documentation
• Payroll module

Keywords

• Payroll API
• Payroll API Response and Error Model

Revision Information

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