Reference Error Codes

This document defines the standard error code taxonomy for PTI v1.0 implementations.

Normative language

The key words MUST: MUST NOT: REQUIRED: SHALL: SHALL NOT: SHOULD: SHOULD NOT: RECOMMENDED: MAY: and OPTIONAL are to be interpreted as described in RFC 2119.

Error response envelope

All error responses MUST use:

{
  "error": {
    "code": "PTI-4001",
    "message": "Unsupported schema version",
    "detail": "trust_event.v2 is not enabled for this tenant",
    "correlation_id": "req_9a8b7c6d",
    "retryable": false,
    "docs_uri": "https://docs.example/pti/errors/PTI-4001"
  }
}

Field	Requirement
`code`	MUST: stable machine identifier
`message`	MUST: short human-readable summary
`detail`	SHOULD, operator-safe elaboration
`correlation_id`	MUST: matches request
`retryable`	MUST: boolean hint for clients
`docs_uri`	OPTIONAL, documentation link

Implementations MUST NOT expose stack traces or internal hostnames in production error bodies.

HTTP status mapping

HTTP	Usage
`400`	Client payload or parameter errors (`PTI-400x`)
`401`	Authentication failure (`PTI-401x`)
`403`	Authorization or policy denial (`PTI-403x`)
`404`	Resource or subject not found (`PTI-404x`)
`409`	Conflict / idempotency (`PTI-409x`)
`422`	Semantic validation (`PTI-422x`)
`429`	Rate limit (`PTI-4290`)
`500`	Internal error (`PTI-500x`)
`503`	Temporary unavailability (`PTI-503x`)

Validation errors (`PTI-400x`)

Code	Message	Retryable
`PTI-4001`	Unsupported schema version	No
`PTI-4002`	Unknown event type	No
`PTI-4003`	Invalid timestamp	No
`PTI-4004`	Missing required field	No
`PTI-4005`	Invalid context_id	No
`PTI-4006`	Payload schema validation failed	No
`PTI-4007`	Invalid pti_id format	No

Authentication errors (`PTI-401x`)

Code	Message	Retryable
`PTI-4010`	Missing credentials	No
`PTI-4011`	Invalid or expired token	No
`PTI-4012`	Invalid signature	No
`PTI-4013`	Credential revoked	No

Authorization errors (`PTI-403x`)

Code	Message	Retryable
`PTI-4030`	Insufficient scope	No
`PTI-4031`	Context not entitled	No
`PTI-4032`	Lookup tier not entitled	No
`PTI-4033`	Consent required	No
`PTI-4034`	Subject suppressed	No
`PTI-4035`	Cross-tenant access denied	No
`PTI-4036`	Producer not enabled for context	No

Access consent alias (`consent_required`)

TumiTrust institution Trust Check and report generate responses MAY return a flat body alias for mobile and partner LOS clients:

{
  "success": false,
  "code": "consent_required",
  "error_type": "consent_required",
  "reason": "consent_required",
  "error": "Active access consent from the member is required before this Trust Check.",
  "partner_id": 123,
  "partner_name": "Demo Bank ZN"
}

HTTP status MUST be 403. Normative mapping: consent_required ≡ PTI-4033. Product language: access consent / member / institution (not lender/borrower).

Not found errors (`PTI-404x`)

Code	Message	Retryable
`PTI-4040`	Resource not found	No
`PTI-4041`	Subject not resolved	No
`PTI-4042`	Report not found or expired	No
`PTI-4043`	Event not found	No

Conflict errors (`PTI-409x`)

Code	Message	Retryable
`PTI-4090`	Identity merge conflict	No
`PTI-4091`	Idempotency key conflict	No
`PTI-4092`	Concurrent modification	Yes

Semantic errors (`PTI-422x`)

Code	Message	Retryable
`PTI-4220`	Event context binding mismatch	No
`PTI-4221`	Retraction target not materialized	No
`PTI-4222`	Assertion signature invalid	No
`PTI-4223`	Policy pack violation	No

Rate limiting (`PTI-429x`)

Code	Message	Retryable
`PTI-4290`	Rate limit exceeded	Yes

Clients SHOULD honor Retry-After headers when present.

Server errors (`PTI-500x`)

Code	Message	Retryable
`PTI-5000`	Internal error	Yes
`PTI-5001`	Downstream registry unavailable	Yes
`PTI-5002`	Intelligence engine timeout	Yes

Service unavailable (`PTI-503x`)

Code	Message	Retryable
`PTI-5030`	Maintenance mode	Yes
`PTI-5031`	Overloaded	Yes

Client handling guidance

Clients MUST log correlation_id for support escalation.
Producers SHOULD persist PTI-4091 conflicts for manual reconciliation.
Consumers MUST NOT retry 403x errors without entitlement change.

Extension rules

Implementations MAY define vendor-specific codes only above PTI-9000. Codes below PTI-9000 are reserved by the PTI specification.

Normative language​

Error response envelope​

HTTP status mapping​

Validation errors (PTI-400x)​

Authentication errors (PTI-401x)​

Authorization errors (PTI-403x)​

Access consent alias (consent_required)​

Not found errors (PTI-404x)​

Conflict errors (PTI-409x)​

Semantic errors (PTI-422x)​

Rate limiting (PTI-429x)​

Server errors (PTI-500x)​

Service unavailable (PTI-503x)​

Client handling guidance​

Extension rules​

Related documents​