Troubleshooting

Common errors

The table below outlines common errors that may occur when integrating Digital Intelligence. These issues can result from SDK initialization problems, environment mismatches, permission denials, or platform restrictions. Understanding these patterns can help you fine-tune your workflows, reduce false negatives, and determine when escalation or fallback logic is appropriate.

Issue	Explanation	Suggested fix
SDK does not return a `sessionToken`	The token is only issued once device data has been captured and uploaded.	Ensure correct SDK key is used. Wait for async handlers to complete. Check error callbacks. Review network/firewall settings to allow Socure backend calls.
API call returns no Digital Intelligence data	Using the wrong type of key or environment mismatch can prevent results.	Use an API key (not SDK key) for server calls. Verify environment (sandbox vs production).
Missing field in response	Some fields depend on permissions or platform support.	Check if permissions (e.g., location) were denied. Note OS/browser restrictions. Some computed fields (e.g., `isVirtualMachine`) may be indeterminate.
Unexpected value in response	SDK reports values as observed by backend without modification.	This is expected. Use anomalies (e.g., injected or manipulated values) as potential risk signals.

How to debug

To debug Digital Intelligence 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 (200 indicates success).
Validate that the Digital Intelligence enrichment module was triggered.
Review device, behavioral, and entity profiler outputs for anomalies or missing values.
Check SDK error callbacks on the client for initialization or permission errors.

Fallback strategies

If Digital Intelligence does not yield expected results:

Retry once SDK completes capture. Wait for async completion handlers.
Validate keys and environments. Confirm correct API vs SDK keys and sandbox vs production.
Handle missing signals gracefully. If certain fields are absent (permissions, platform limits), do not block the workflow — instead, rely on other signals.
Escalate to review. Use tags or review_queues in RiskOS to route inconclusive sessions for human analysis.

Escalation path

For production-impacting issues or debugging edge cases:

Reproduce the issue. Do this in the sandbox or staging environment if possible.
Capture relevant identifiers. Collect:
- eval_id
- Full request payload
- referenceId from the Digital Intelligence enrichment
Open a support ticket. Contact Socure Support or your Technical Account Manager (TAM) and include:
- 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 limitations

Permission-dependent signals. Certain fields (e.g., location) require explicit user permission.
Platform restrictions. Some browsers and OS versions limit available device attributes.
Indeterminate computed values. Certain flags (e.g., isVirtualMachine) are only populated when a definitive determination can be made.
Observed values only. Digital Intelligence reports exactly what the SDK/backend detects — anomalies may represent tampering or malicious injection attempts.

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