Error Tag Catalog

This page centralizes the most common error.major.tag values across services. Service pages remain the canonical source for exact status codes and tag meanings; use this page for quick cross-service orientation.

Canonical error envelope (required)

Errors use the common response envelope (success=false) with a stable error object. All services should emit these fields; existing services may add them incrementally without breaking clients.

Required/standard fields:

error_code: stable string identifier for client logic and analytics (required format: <svc>.<code>[.<detail>]).
major.tag: canonical classification tag (see catalog below).
major.message.en_US: human-readable message.
http_status: numeric HTTP status returned for the request.
retryable: boolean hint for safe retries.
request_id: should mirror stats.request_id for correlation.
trace_id: optional trace correlation identifier.
details: optional structured payload (field-level errors, policy context, etc.).
conflict_snapshot: optional snapshot of current state for 409 conflicts.

Notes:

minor is optional and used for more specific categorization (e.g., invalid-input → invalid-input.missing-field).
error_code is the stable key for SDKs; tags remain human-friendly and cross-service.
conflict_snapshot is included only when safe and necessary for conflict resolution.

Error object schema (canonical)

json

{
  "error": {
    "error_code": "pvm.validation_failed.missing_field",
    "http_status": 400,
    "retryable": false,
    "request_id": "req-123",
    "trace_id": "trace-abc",
    "major": { "tag": "validation-error", "message": { "en_US": "Missing required field." } },
    "minor": { "tag": "missing-field", "message": { "en_US": "Field is required." } },
    "details": {
      "fields": [
        { "path": "style.caption", "rule": "required", "message": "caption is required" }
      ]
    },
    "conflict_snapshot": { "revision": "rev-abc", "current_record": { "id": "..." } }
  }
}

Field-level validation details are UNCONFIRMED across services today. Target posture:

details.fields[] with { path, rule, message } for validation errors.
details.context for policy failures (role, org status, facility gating).
details.current_revision and details.current_record (bounded) for conflicts.

error_code naming rules (canonical)

Format: <svc>.<category>[.<detail>] (lowercase, dot-separated).
<svc> is the service short name (pvm, pmc, scm, ics, etc.).
<category> maps to error.major.tag where possible.
<detail> is optional but recommended for specific client handling.

Example: scm.conflict_revision, usm.auth_invalid, ics.validation_failed.invalid-zone.

HTTP status mapping (baseline)

HTTP	Tag	Usage
400	`validation-error` / `invalid-input`	Missing/invalid fields, schema violations.
401	`unauthorized`	Missing or invalid session/API key.
403	`forbidden` / `org-write-blocked`	Valid auth but insufficient role, ownership, or org status.
404	`not-found`	Missing resource or anti-enumeration.
409	`conflict` / `invalid-state`	Revision mismatch or invalid state transition.
410	`gone`	Expired/retired resources (tokens, sessions, etc.).
428	`expected-revision-required`	Missing optimistic concurrency token.
429	`throttled`	Transient throttling or concurrency guard.
500	`internal-error`	Server error; retry with backoff.

If an endpoint uses a different mapping, the service surface page must document it explicitly.

Conflict snapshot usage

conflict_snapshot is only returned when it is safe to expose the current record.
When present, it should include the current revision and a bounded summary (no PII/secrets).
If omitted, clients should re-read via the appropriate get endpoint.

Differences between services (current)

OFM uses invalid-input in places where other services use validation-error.
MRS uses idempotency-conflict for idempotency_key replays with different payloads.
USM uses invalid-api-key / invalid-passcode for auth failures.

Standardization plan:

Converge all services on the canonical error object and HTTP mapping table.
Expand field-level validation details across all API Gateway surfaces.

Canonical error_code catalog (baseline)

These codes are required for cross-service consistency. Service pages may extend them, but must not change meanings. Format: <svc>.<code> where <svc> is the service short name (e.g., pvm, pmc, scm).

<svc>.auth_required: missing auth context.
<svc>.auth_invalid: invalid session or api key.
<svc>.auth_expired: expired session or revoked api key.
<svc>.org_not_associated: anti-enumeration 404 for unassociated access.
<svc>.org_write_blocked: org status prevents writes.
<svc>.role_forbidden: valid auth but insufficient role/permission.
<svc>.context_mismatch: header/body/query context mismatch (orgcode/session/api_key/cccode).
<svc>.validation_failed: request validation failed (schema or business rules).
<svc>.conflict_revision: expected_revision mismatch.
<svc>.conflict_idempotency: same idempotency_key, different payload.
<svc>.conflict_state: invalid state transition.
<svc>.rate_limited: throttling or concurrency protection triggered.
<svc>.dependency_unavailable: upstream dependency not healthy.
<svc>.timeout: request exceeded allowed time budget.
<svc>.not_supported: feature or route not supported in this deployment.

Cross-service tags (common)

Tag	Meaning	Typical HTTP	Retry guidance
`validation-error`	Missing/invalid required fields	400	Fix request; do not retry as-is.
`invalid-input`	Input failed validation rules	400	Fix request; do not retry as-is.
`unauthorized`	Auth failed (bad or missing credential)	401	Fix auth; do not retry as-is.
`forbidden` / `forbidden-role` / `not-owner`	Authenticated but not permitted	403	Fix role/ownership; do not retry as-is.
`org-write-blocked`	Org is not verified for writes	403	Verify org status; do not retry as-is.
`not-found`	Resource missing or anti-enumeration	404	Run self-check first; do not retry blindly.
`expected-revision-required`	Missing optimistic concurrency token	428	Read current record and retry with `expected_revision`.
`conflict`	Optimistic concurrency mismatch	409	Read current record and retry with new `expected_revision`.
`invalid-state` / `invalid-fsm-transition`	FSM/state does not allow the operation	409	Fix state, then retry.
`throttled`	Rate/limit guardrail hit	429	Retry with backoff and jitter.
`internal-error`	Server-side error	500	Retry with backoff; open a support issue if persistent.

Service-specific tags

UAS

Tags documented in https://doc.g3nretailstack.com/uas/:

duplicate-email, invalid-token, token-expired, invalid-transition
passcode-policy-failed, passcode-reuse, payment-uniqueness-conflict
not-found, validation-error, unauthorized, internal-error
expected-revision-required, conflict

USM

Tags documented in https://doc.g3nretailstack.com/usm/:

invalid-passcode, invalid-api-key
user-not-verified, email-not-verified
too-many-sessions, session-cap-invalid
session-not-found, session-doomed, ttl-expired
user-suspended, user-doomed, email-unverified, email-doomed
invalid-status, missing-session, validation-error, internal-error

OFM

Tags documented in https://doc.g3nretailstack.com/ofm/:

invalid-code, invitation-consumed, invitation-expired
uniqueness-conflict, code-generation-exhausted, duplicate-member
invalid-depth, external-id-active-in-use
not-owner, invalid-fsm-transition, invalid-session
invalid-input, not-found, throttled, internal-error
expected-revision-required, conflict, invalid-state

MRS

Tags documented in https://doc.g3nretailstack.com/mrs/:

invalid-session, invalid-tag, inline-too-large, missing-size, size-mismatch, too-large
unsupported-content-type, gzip-required, missing-content-md5, invalid-content-md5, md5-missing, md5-mismatch
not-found, doomed, invalid-status, idempotency-conflict
throttled, internal-error, expected-revision-required, conflict

PVM

Tags documented in https://doc.g3nretailstack.com/pvm/:

invalid-input, forbidden, unauthorized, not-found
conflict, invalid-state, invalid-check-digit
code-generation-exhausted, throttled, internal-error
expected-revision-required

PMC

Tags documented in https://doc.g3nretailstack.com/pmc/:

invalid-input, forbidden-role, unauthorized, not-found
conflict, expected-revision-required, invalid-state
upstream-failed, internal-error

ICS

Tags documented in https://doc.g3nretailstack.com/ics/:

invalid-input, forbidden-role, unauthorized, invalid-session, not-found
conflict, expected-revision-required, invalid-state, invalid-fsm-transition
org-write-blocked, org-access-blocked, idempotency-conflict
throttled, dependency-unavailable, timeout, session-validate-failed, internal-error

PPM

Tags documented in https://doc.g3nretailstack.com/ppm/:

invalid-input, validation-error, forbidden, forbidden-role, unauthorized, invalid-session, not-found
conflict, expected-revision-required, invalid-state, invalid-fsm-transition, idempotency-conflict
org-write-blocked, org-access-blocked
throttled, dependency-unavailable, timeout, not-implemented, internal-error

SCM

Tags documented in https://doc.g3nretailstack.com/scm/:

invalid-input, validation-error, forbidden, forbidden-role, unauthorized, invalid-session, not-found
conflict, expected-revision-required, invalid-state, invalid-fsm-transition, idempotency-conflict
org-write-blocked, org-access-blocked
throttled, dependency-unavailable, timeout, not-implemented, internal-error

PCM

Tags documented in https://doc.g3nretailstack.com/pcm/:

invalid-input, validation-error, forbidden, forbidden-role, unauthorized, invalid-session, not-found
conflict, expected-revision-required, invalid-state, invalid-fsm-transition, idempotency-conflict
org-write-blocked, org-access-blocked
throttled, dependency-unavailable, timeout, not-implemented, internal-error

CRM

Tags documented in https://doc.g3nretailstack.com/crm/:

invalid-input, validation-error, forbidden, forbidden-role, unauthorized, invalid-session, not-found
conflict, expected-revision-required, invalid-state, invalid-fsm-transition, idempotency-conflict
org-write-blocked, org-access-blocked
throttled, dependency-unavailable, timeout, not-implemented, internal-error

Influencer

Tags documented in https://doc.g3nretailstack.com/influencer/:

invalid-input, validation-error, forbidden, forbidden-role, unauthorized, invalid-session, not-found
conflict, expected-revision-required, invalid-state, invalid-fsm-transition, idempotency-conflict
payout-not-ready, org-write-blocked, org-access-blocked
throttled, dependency-unavailable, timeout, not-implemented, internal-error

Accounting

Tags documented in https://doc.g3nretailstack.com/accounting/:

invalid-input, validation-error, forbidden, forbidden-role, unauthorized, invalid-session, not-found
conflict, expected-revision-required, invalid-state, invalid-fsm-transition, idempotency-conflict
org-write-blocked, org-access-blocked
throttled, dependency-unavailable, timeout, not-implemented, internal-error

IPM

Tags documented in https://doc.g3nretailstack.com/ipm/:

invalid-input, validation-error, forbidden, forbidden-role, unauthorized, invalid-session, not-found
conflict, expected-revision-required, invalid-state, idempotency-conflict
org-write-blocked, org-access-blocked
throttled, dependency-unavailable, timeout, not-implemented, internal-error

RBS

Tags documented in https://doc.g3nretailstack.com/rbs/:

invalid-input, validation-error, forbidden, forbidden-role, unauthorized, invalid-session, not-found
conflict, expected-revision-required, invalid-state, invalid-fsm-transition, idempotency-conflict
org-write-blocked, org-access-blocked, payload-too-large
throttled, dependency-unavailable, timeout, not-implemented, internal-error

UTL

Tags documented in https://doc.g3nretailstack.com/utl/:

invalid-input, invalid-session, forbidden, not-found
invalid-state, conflict, export-bucket-missing
internal-error

Notes

HTTP status codes are typical and may vary by endpoint; always check the service surface page.
For anti-enumeration guidance, see /common/troubleshooting.html.
For retry rules, see /common/idempotency-retry.html.

Error Tag Catalog ​

Canonical error envelope (required) ​

Error object schema (canonical) ​

error_code naming rules (canonical) ​

HTTP status mapping (baseline) ​

Conflict snapshot usage ​

Differences between services (current) ​

Canonical error_code catalog (baseline) ​

Cross-service tags (common) ​

Service-specific tags ​

UAS ​

USM ​

OFM ​

MRS ​

PVM ​

PMC ​

ICS ​

PPM ​

SCM ​

PCM ​

CRM ​

Influencer ​

Accounting ​

IPM ​

RBS ​

UTL ​

Notes ​