Troubleshooting

Common errors

The table below outlines common errors that may occur when using OTP Verification in RiskOS™. These issues can result from formatting problems, unsupported phone numbers, or OTP policy limits. Understanding these patterns can help you fine-tune workflows, reduce friction, and improve security.

Issue	Explanation	Suggested fix
API returns `Invalid phone number`	The phone number is not formatted correctly. Must follow E.164 format.	Ensure phone number is in `+{country_code}{number}` format (e.g., `+15034700244`). Remove spaces/dashes. Confirm it’s valid SMS.
Verification always returns `pending`	OTP has not yet been verified but is still within the 10-minute window.	Wait for user to submit OTP. Confirm delivery succeeded. Check expiration and retry count.
Voice call not received	Destination may not support voice delivery.	Confirm the number can accept calls. Note some VoIP or virtual numbers may not support voice OTP.
OTP verification rejected	Retry or expiration limits have been exceeded.	Ensure user has not exceeded 5 attempts or the 10-minute expiration period.
401 Unauthorized	Invalid or expired API token.	Verify Bearer token is correct and active. Use correct token for sandbox vs production.
403 Forbidden	API token lacks permissions.	Contact support to enable OTP access. Confirm account entitlements.
Missing required fields	Payload missing destination or channel.	Include all mandatory fields. Check names are case-sensitive. Ensure phone numbers are in E.164.
Evaluation not found on PATCH	Invalid or expired `eval_id`.	Verify you’re using the correct `eval_id`. Check same environment (sandbox vs production). Confirm UUID format.
OTP delivery failed	No OTP received by user. Missing enrichment response.	Confirm valid mobile/email. Check carrier or inbox deliverability. Retry with alternate destination if needed.
Invalid OTP	OTP entered by the user is incorrect	OTP entered by the user is incorrect. OTP will be six digit numeric

How to debug

To debug OTP 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 status should be flagged.
Validate the correct channel (SMS, email, voice) was triggered.
Review the OTP status (pending, approved, reject). Confirm expiry and retry counts.
Check the verificationId is consistent across delivery and verify requests.

Fallback strategies

If OTP does not yield a successful verification:

Retry delivery: Allow resend if OTP is not received.
OTP expires:Allow resend if OTP expires before verification
Switch channels: If SMS fails, attempt email or voice delivery.
Force resume: Use the force_resume_evaluation flag if workflow stalls.
Escalate to review: Route persistent OTP failures to manual review.

Escalation path

For production-impacting issues or debugging edge cases:

Reproduce the issue in sandbox or staging if possible.
Capture relevant identifiers, including:
- eval_id
- Full request payload
- verificationId from OTP enrichment
Open a support ticket — Contact Socure Support or your Solutions Consultant team and include workflow name, request details, and logs.
Urgent escalation — Use Slack (if integrated) or your designated Socure escalation channel for high-severity cases.

Known limitations

Carrier dependency: SMS/voice OTP delivery may vary by carrier or region.
OTP window: Codes typically expire in 10 minutes. Expired codes always fail verification.
Retry limits: Max of 5 attempts per OTP session. Further attempts auto-fail.
Channel restrictions: Some VoIP/virtual numbers may not support SMS or voice delivery.
No storage of OTP codes: For security, OTP values are never logged or retrievable.

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