Skip to main content

Anti-Patterns

Common mistakes when implementing PTI — and the corrective patterns that avoid them.

Identity​

Embedding PII in pti_id​

Problem: Custom identifiers encode phone numbers or national IDs, creating leakage risk and merge failures.

Fix: Use registry-allocated opaque pti_id values only.

Ignoring merge webhooks​

Problem: Producer continues sending events to a merged (retired) pti_id.

Fix: Subscribe to identity.merged and update local mapping tables to the survivor ID.

Treating low-confidence matches as certain​

Problem: Auto-decisioning on weak match confidence (for example 0.62).

Fix: Apply confidence thresholds; require secondary verification for high-impact decisions.

Ingest​

Random idempotency keys​

Problem: Every retry creates duplicate signals.

Fix: Use deterministic keys per business action (see Best Practices).

Using ingest time as occurred_at​

Problem: Skews decay and misorders historical backfill.

Fix: Always send the true activity time; keep ingested_at as a separate server-set field.

Oversized payloads​

Problem: Entire CRM records stuffed into payload, violating minimization.

Fix: Emit schema-required fields only; keep additional data in your own systems.

Context sprawl​

Problem: Producer enables every context “just in case.”

Fix: Enable only entitled, observed contexts; request catalog additions when needed.

Consumer​

Single global score​

Problem: UI collapses lending, rental, and merchant into one number.

Fix: Present context scores separately with per-context drivers.

Thin data as approval​

Problem: A high band is treated as “no risk” when coverage_gaps is non-empty.

Fix: Surface gaps clearly; treat thin bands as inconclusive.

Stale report reuse​

Problem: A months-old report is used for a live decision without regeneration.

Fix: Check generated_at; regenerate or reject expired reports.

Skipping verification​

Problem: PDF or JSON accepted without a verify_uri check.

Fix: Call the verify endpoint for audit-sensitive workflows.

Security​

Shared producer and consumer credentials​

Problem: One API key used for ingest and lookup — weak audit trail.

Fix: Separate credentials and scopes per role.

Disabled TLS verification​

Problem: MITM exposure in partner integrations.

Fix: Always validate certificates in production; use mTLS for high-assurance profiles.

Logging full PII​

Problem: Request bodies with national IDs land in application logs.

Fix: Log correlation_id, pti_id, and hashed identifiers only.

Architecture​

Bypassing the exchange​

Problem: Producer writes directly to a consumer database or shared cache.

Fix: All signals flow through the Exchange for policy, provenance, and audit.

Client-side scoring​

Problem: Consumer reimplements the intelligence engine locally.

Fix: Consume server-derived scores; use drivers for transparency only.

Silent schema drift​

Problem: Client ignores unknown JSON fields and breaks when new required fields appear.

Fix: Pin X-PTI-Version; monitor /capabilities deprecations.

Corrections​

Deleting bad events​

Problem: Hard delete without an audit trail.

Fix: Issue .corrected or .retracted lifecycle events.

Detection checklist​

SymptomLikely anti-pattern
Duplicate signals on retryRandom idempotency keys
Score jumps after backfillWrong occurred_at
Challenge on explainabilityGlobal score UI
Cross-tenant data leakMissing tenant filter