Skip to main content

Expense Gateway and Compatibility Troubleshooting

Summary​

ESS or HR Operations behavior differs, compatibility workspace is incomplete, route ownership is unexpected, or parity/cutover checks fail.

Audience​

  • Employees, managers, HR administrators, support engineers, developers, QA engineers, DevOps engineers, and solution architects, as applicable to the symptom.

Cause​

Use the verified possibilities in Likely causes; do not infer an environment-specific cause without evidence.

Resolution​

Use Safe resolution, then complete Validation. Stop and escalate if the required action exceeds approved access.

Symptoms​

ESS or HR Operations behavior differs, compatibility workspace is incomplete, route ownership is unexpected, or parity/cutover checks fail.

Scope​

Gateway Expense route ownership, ESS proxy, compatibility endpoints, native APIs, parity, cutover, and routing rollback.

Likely causes​

  • Different UI surfaces call native vs compatibility APIs
  • Gateway route ownership differs from expectation
  • Compatibility workspace intentionally owns only Expense slice
  • Legacy/native identity or status shape differs
  • Parity invariant failed
  • Routing rollback occurred without data reconciliation

Safe diagnostic steps​

  • Identify exact UI surface and route family
  • Confirm intended gateway route source through approved diagnostics
  • Compare supported native/compatibility responses using parity tooling
  • Review cutover evidence and write window
  • Stop on parity failure; do not change routing or data without approval

Safe resolution​

Use the approved cutover/rollback runbook and owner decision. After routing rollback, reconcile writes and downstream projections; do not assume data was undone.

Validation​

Route ownership, compatibility/native parity, claim state, and downstream evidence satisfy the approved acceptance criteria.

Evidence to collect​

Route family/source category, deployment/cutover phase, parity result, time window, claim-count/status categories, correlation evidence.

Escalation​

Gateway/platform owner, Expense owner, migration/cutover owner, and product/Finance for business discrepancies.

Requires confirmation​

Any corrective action beyond the supported resolution, incident ownership, response objectives, and production evidence locations require confirmation.

Source References​

  • microservices/src/gateway-api/Program.cs
  • microservices/src/expense-service/Api/ExpenseCompatEndpoints.cs
  • microservices/scripts/compare-expense-parity.ps1
  • microservices/docs/expense-cutover-runbook.md

See Also​

Keywords​

  • Expense troubleshooting
  • Gateway and Compatibility

Revision Information​

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