Troubleshooting

Common errors

Issue	Explanation	Suggested Fix
`400 invalid_phone`	The phone number is not formatted in E.164, causing the request to be rejected.	Format the phone number correctly, for example: `+14155551234`.
Prefill empty	The Prefill workflow did not return results because the input data was too limited.	Add additional identifiers such as email or address, and confirm that the Device Intelligence token is present.
`OTP fails`	The One-Time Passcode (OTP) validation failed due to an incorrect `eval_id` or an expired code.	Resend the OTP with a valid evaluation session and ensure the correct `eval_id` is used.
DocV stuck `ON_HOLD`	The document verification process was paused or abandoned by the user.	Implement retry logic and route the session to manual review if the user does not complete the flow.
Webhook not firing	The webhook callback is not reaching your endpoint due to a configuration issue.	Verify the webhook URL is HTTPS, and ensure headers and signatures are correctly configured.

Error codes

Code	Example Response	Explanation	Suggested Fix
400	`{ "error": "invalid_phone" }`	Input malformed	Validate phone E.164, DOB ISO 8601
422	`{ "error": "unsupported_schema" }`	Region or schema not supported	Check `address.country`, remove unsupported fields
429	`{ "error": "rate_limit" }`	Too many requests	Retry with exponential backoff + jitter
500	`{ "error": "server_error" }`	Transient backend error	Retry with backoff; escalate if persistent

OTP Issues

Symptom	Explanation	Suggested Fix
No OTP delivered	Carrier filtering or bad format	Verify E.164 input. Test across carriers
OTP always fails	Wrong `eval_id` or expired code	Confirm `PATCH` uses correct ID and active session
OTP passes but no Prefill	Suppression tag set	Don’t display data; require manual entry

Example PATCH failure

{
  "error": "otp_invalid",
  "message": "The OTP code is invalid or expired"
}

DocV Issues

Symptom	Explanation	Suggested Fix
DocV never triggers	Workflow thresholds not configured	Enable DocV in RiskOS™ workflow editor
DocV session fails	Missing DI token in web flow	Embed DI SDK when hosting DocV externally
DocV stuck `ON_HOLD`	User abandoned	Add retries + reminders; route to manual

Webhook payload (DocV COMPLETED)

{
  "eval_id": "123",
  "decision": "APPROVE",
  "status": "COMPLETED",
  "data_enrichments": [ ... ]
}

Webhook Debugging

Verify signatures: All webhook requests include headers to validate authenticity.
Expect retries: RiskOS™ retries up to 3 times on failure. Respond 200 to stop retries.
Log full payloads: Always capture eval_id + decision.

Performance

Latency target: 300ms median.
If higher: check network, SDK initialization timing, and server location.
Profile both client-side and server-side latency.

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 the following:
- eval_id
- Full request payload
- referenceId from the Verify enrichment (if applicable)
Open a support ticket. Contact Socure Support or your Solutions Consultant team 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

Common failure scenarios with example payloads

These sandbox-ready examples let you reproduce failures end-to-end and verify your integration’s error-handling logic. Use them to simulate common scenarios and confirm your workflow responds correctly.

Invalid Phone (400)

curl -X POST https://riskos.sandbox.socure.com/api/evaluation \
  -H "Authorization: Bearer YOUR_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "{{$randomUUID}}",
    "timestamp": "2025-09-11T12:00:00Z",
    "workflow": "alt_advanced_pre_fill",
    "data": {
      "individual": {
        "phone_number": "123456",  
        "date_of_birth": "1990-05-15",
        "di_session_token": "sess_bad"
      }
    }
  }'

Example response - Unsupported schema (422)

{
  "error": "unsupported_schema",
  "message": "Address country not supported"
}

Example response - Rate limit (429)

{
  "error": "rate_limit",
  "message": "Too many requests, slow down"
}

Example response - One-Time Passcode failure

{
  "error": "otp_invalid",
  "message": "The OTP code is invalid or expired"
}

Example response - Prefill empty

{
  "decision": "DECLINE",
  "status": "COMPLETED",
  "reasonCodes": ["I520"],
  "message": "No identity found for provided inputs"
}