Troublshooting

Common errors

The table below outlines common errors that may occur when calling the Email Risk enrichment. These issues often stem from input formatting, incomplete or invalid data, velocity anomalies, or evolving model behaviors. Understanding these patterns can help you fine-tune workflows, reduce false positives, and determine when escalation or fallback logic is appropriate.

Issue	Explanation	Suggested fix
No score or API error	Missing or invalid email field (blank, typos, unsupported domain formats); email too long or with bad chars; invalid `customerUserId`.	Validate email formatting (RFC-compliant, supported TLD). Ensure `customerUserId` ≤100 characters and standard charset. Confirm schema and headers in API call.
High risk (R520)	Email exhibits patterns linked to fraud (disposable domains, new creation, velocity anomalies, confirmed fraud history).	Step up verification (e.g., phone, address, document scan). Cross-reference internal lists. Escalate to manual review if corroborating risk signals exist.
Low risk (I520) but other workflow issue	Email is durable, stable, and not tied to fraud, but other signals (phone, device, velocity) may still fail.	Proceed with email as a positive signal, but review companion data (device, phone, address) before making a decision.
Failed email validation / formatting	Syntax or character set errors; unsupported domains; non-RFC-compliant input.	Confirm valid format (`[email protected]`), correct domain, and RFC compliance. Strip invalid characters and resubmit.
Variable scores across transactions	Velocity spikes (multiple applications), disposable domain cycling, or updated model calibrations.	Track score trends over time. Use multi-signal inputs (name, phone, address) for balance. Escalate unusual variability.
Velocity anomaly (R523)	Rapid, repeated use of the same email suggests bot attack or fraud ring activity.	Review velocity patterns and thresholds. Escalate high-frequency anomalies for manual review or further checks. Adjust session and velocity controls.
Disposable domain (R524)	Email comes from a known temporary/disposable provider.	Request a permanent email address or escalate for manual review.
Confirmed fraud (R525)	Email linked to past fraud attempts in Socure or external sources.	Block or send for thorough manual review.
Email RiskScore not updating	Risk score only refreshes if the email itself changes or new behaviors are observed.	Confirm new email is submitted in the API call. Validate request payload structure.

How to debug

To debug Email Risk behavior in RiskOS™:

Use the eval_id to trace execution in the Developer Console or RiskOS logs.
Check the status_code in each data_enrichments[] block. A 200 indicates success. Any other code should be flagged.
Validate that the emailRisk enrichment was triggered. If not, confirm email was present and correctly formatted.
Review reasonCodes for signals such as velocity anomalies, disposable domains, or invalid formats.
Examine returned scores. A high score (≥0.97) = elevated risk; a low score (≤0.20) = low risk.
Confirm nameEmailCorrelation was returned if given_name and family_name were provided. Low correlation may drive review outcomes.

Fallback strategies

If Email Risk does not yield a clear result:

Reprompt for correction. Ask users to re-enter the email if validation fails or unsupported domains are detected.
Chain enrichments. Use phone verification, document upload, or device risk signals for additional confidence.
Step up verification. Trigger OTP or documentary verification when R520, R523, or R524 codes are present.
Escalate to review. Use tags or review_queues to route suspicious or inconclusive cases to analysts.

Escalation path

For production-impacting issues or debugging edge cases:

Reproduce the issue. Try in sandbox/staging with the same payload.
Capture identifiers. Collect:
- eval_id
- Full request payload
- referenceId from the Email Risk enrichment
Open a support ticket. Contact Socure Support or your Technical Account Manager (TAM) with:
- Workflow name
- Input fields submitted
- Expected vs. actual decision
- Logs or screenshots (if applicable)
Urgent escalation. For high-severity cases, escalate via:
- Slack (if integrated)
- Your designated Socure escalation channel

Known issues

Overlapping signals: Multiple risk indicators related to similar behaviors may be returned together. Customers should define how to prioritize or interpret related signals within their workflow logic.
Limited input context: Submissions with minimal identity information may provide less context for risk assessment. Providing additional attributes, when available, can improve signal confidence.
Score variability over time: Risk assessments may vary slightly over time based on changing inputs or underlying patterns. Scores are best evaluated in context rather than as fixed values.
Input normalization: Inconsistent formatting or unsupported character encoding in email addresses may affect processing. Normalizing inputs before submission can help ensure consistent results.
Positive context signals: Some signals may indicate stability or longevity (such as established email or domain characteristics) and should be considered as part of the overall risk context, even when other indicators are present.