Advanced Prefill Troubleshooting & FAQs

Troubleshooting

Common errors

Error codes

OTP Issues

Example PATCH failure

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

DocV Issues

Webhook payload (DocV COMPLETED)

{
  "eval_id": "123",
  "decision": "ACCEPT",
  "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:

1. Reproduce the issue. Do this in the sandbox or staging environment if possible.
2. Capture relevant identifiers. Collect the following:
   • eval_id
   • Full request payload
   • referenceId from the Verify enrichment (if applicable)
3. 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)
4. 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": "REJECT",
  "status": "COMPLETED",
  "reasonCodes": ["I520"],
  "message": "No identity found for provided inputs"
}

FAQs

General product behavior