Troubleshooting

Common errors

The table below outlines common errors that may occur when evaluating addresses with Socure Address Risk. These issues can result from incomplete inputs, formatting problems, or model version changes. Understanding these patterns can help you fine-tune your workflows, reduce false positives, and determine when escalation or fallback logic is appropriate.

Issue	Explanation	Suggested fix
Low correlation or unexpected risk scores	Incomplete or poorly structured input. Address elements (e.g., apartment/unit) missing or misformatted. Name and address may not historically correlate.	Provide full name and complete address. Submit apartment/unit numbers in a dedicated field. Ensure address is formatted per USPS standards. Validate inputs with an address verification service before submission.
Missing or invalid output	Required fields (name or address) not provided, request misformatted, or encoding issues.	Confirm both name and address fields are present. Check request format against docs. Use UTF-8 encoding and avoid unsupported characters.
Frequent errors or API failures	Rate limits exceeded, authentication problems, or incorrect endpoint usage.	Monitor request volume to stay within rate limits. Validate API keys/tokens. Verify endpoint URLs and review recent API updates in DevHub.
Unexpected model behavior after release updates	Model version changed with new logic or data sources. Thresholds or rules not updated to align with the latest version.	Check current model version. Review release notes for logic changes. Re-evaluate thresholds and rules based on updated performance. Contact Socure for tuning recommendations.

How to debug

To debug Address 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. Other codes should be flagged.
Confirm required inputs (name and structured address fields) were provided.
Review reasonCodes for insight into anomalies such as vacant addresses, commercial locations, or unsupported formats.
Verify encoding and field formats align with expected standards (UTF-8, ISO codes, USPS formatting).

Fallback strategies

If Address Risk does not yield a confident result:

Enable partial match tolerance. Accept lower correlation thresholds in low-risk flows.
Use secondary enrichments. Pair with KYC, Email Risk, or Phone Risk modules for added confidence.
Retry with normalized inputs. Ensure address parsing and casing are consistent, and resubmit.
Escalate to review. Use tags or review_queues to route inconclusive results to human analysts.

Escalation path

For production-impacting issues or debugging edge cases:

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

Known issues

Address formatting dependencies. Missing apartment/unit numbers or non-standardized formats reduce accuracy.
Coverage limitations. Some geographies may have limited address validation or correlation coverage.
Encoding issues. Non-UTF8 characters or unnormalized Unicode inputs may trigger enrichment failures. Normalize inputs before submission.
Model version drift. Behavior may change across model updates; thresholds may need to be re-tuned.

📘
Note:
Use the Developer Console to view raw request/response logs in real time for debugging or validation.