svc-tenders Error Surface Map

Purpose

This note documents the recurring error families in the densest svc-tenders route modules after Cleanup Sprint 37.

Focus:

• 400 validation/input failures
• 403 visibility/capability/ingress denials
• 404 not-found surfaces
• 409 state/conflict/domain-transition failures

Labels used here:

• VERIFIED
• REAL
• TRANSITIONAL

registerTenderDeclarationRoutes.ts

Route module:

• services/svc-tenders/src/routes/registerTenderDeclarationRoutes.ts

Error cluster:

• admin read

Dominant status family:

• 400
• 403
• 404

Classification:

• validation/input
• capability/visibility
• not-found

Notes:

• VERIFIED
• read routes mainly fail on invalid locator, broader visibility denial, or missing declaration

Error cluster:

• draft authoring

Dominant status family:

• 400
• 403
• 404
• 409

Classification:

• validation/input
• stricter mutation denial
• not-found
• conflict

Notes:

• VERIFIED
• update flows introduce 404 missing draft target and 409 draft-state or ID-mismatch conflicts

Error cluster:

• readiness / declare transitions

Dominant status family:

• 400
• 403
• 404
• 409

Classification:

• validation/input
• broader or stricter capability denial
• not-found
• conflict

Notes:

• VERIFIED
• 409 here is primarily readiness/state-machine conflict rather than repository uniqueness conflict

Error cluster:

• evidence surface

Dominant status family:

• 400
• 403
• 404
• 409

Classification:

• validation/input
• capability/visibility
• not-found
• conflict

Notes:

• VERIFIED
• upload adds 400 upload/evidence-group failures and 409 draft-state conflict before persistence

registerAuctionDeclarationRoutes.ts

Route module:

• services/svc-tenders/src/routes/registerAuctionDeclarationRoutes.ts

Error cluster:

• output-allocation admin surface

Dominant status family:

• 400
• 403
• 404

Classification:

• validation/input
• broader or stricter capability denial
• not-found

Notes:

• VERIFIED
• this cluster does not currently use the same rich 409 state-machine pattern as declaration transitions

Error cluster:

• admin read

Dominant status family:

• 400
• 403
• 404

Classification:

• validation/input
• capability/visibility
• not-found

Error cluster:

• evidence surface

Dominant status family:

• 400
• 403
• 404
• 409

Classification:

• validation/input
• capability/visibility
• not-found
• conflict

Notes:

• VERIFIED
• unlike tender evidence upload, this cluster can return stricter mutation denial on upload because the write path stays behind auction:create-draft

Error cluster:

• draft authoring

Dominant status family:

• 400
• 403
• 404
• 409

Classification:

• validation/input
• stricter mutation denial
• not-found
• conflict

Notes:

• VERIFIED
• draft create/update can additionally fail on missing output allocation because declaration flow is still colocated with allocation dependencies

Error cluster:

• readiness / announce transitions

Dominant status family:

• 400
• 403
• 404
• 409

Classification:

• validation/input
• broader or stricter capability denial
• not-found
• conflict

Notes:

• VERIFIED
• 409 here is the announce/readiness conflict family rather than a generic repository failure

Unresolved or transitional notes:

• TRANSITIONAL
• auction declarations still mix declaration error families with output-allocation error families in one module

registerKesRoutes.ts

Route module:

• services/svc-tenders/src/routes/registerKesRoutes.ts

Error cluster:

• case entry

Dominant status family:

• 400
• 500

Classification:

• validation/input
• write failure

Notes:

• VERIFIED
• case creation is an outlier in this cluster because it surfaces 500 create failure rather than the more common 409 action conflict family

Error cluster:

• operator read / control-plane surface

Dominant status family:

• 400
• 404

Classification:

• validation/input
• not-found

Notes:

• VERIFIED
• aggregate reads often return empty/default shapes instead of conflict responses

Error cluster:

• process-map mutation

Dominant status family:

• 400
• 409

Classification:

• validation/input
• conflict

Error cluster:

• case / task / inspection actions

Dominant status family:

• 400
• 404
• 409

Classification:

• validation/input
• not-found
• conflict

Notes:

• VERIFIED
• create-like actions such as task assignment and inspection submission skew toward 404 missing case, while lifecycle transitions skew toward 409 invalid state

Error cluster:

• payment-sensitive actions

Dominant status family:

• 400
• 403
• 404
• 409

Classification:

• validation/input
• ingress denial
• not-found
• conflict

Notes:

• VERIFIED
• payment request is the strictest error stack because it can fail on KYC-boundary validation before signature verification
• approve/settle replace KYC failures with signature-only ingress denial

Error cluster:

• case closure

Dominant status family:

• 400
• 409

Classification:

• validation/input
• conflict

Notable asymmetry:

• VERIFIED
• KES alone carries ingress/security-specific 403 denial patterns in this dense cluster
• declaration routes center more on capability-denial and state-machine 409 families

Unresolved or transitional notes:

• TRANSITIONAL
• KES error families still sit on a root-repository-derived persistence slice rather than a fully isolated child repository

Current Asymmetry

VERIFIED

The recurring error families remain intentionally different:

• tender and auction declarations share the same broad 400 / 403 / 404 / 409 family, but auction additionally mixes in output-allocation-specific not-found/input paths
• tender evidence upload uses broader visibility denial, while auction evidence upload uses stricter mutation denial
• KES introduces ingress-specific 403 denial and a 500 case-create failure surface that declaration routes do not use