Troubleshooting
Learn how to test, debug, and recover from common Hosted Flows issues in RiskOS™.
Common errors
The table below summarizes frequent errors encountered in Hosted Flows, why they happen, and how to resolve them.
| Issue | Explanation | Suggested fix |
|---|---|---|
| Invalid token | API credentials are missing, expired, or misconfigured. | Rotate/regenerate API keys; verify environment (Sandbox vs. Prod); confirm auth header format. |
| Session timeout | User was inactive beyond the configured session window. | Increase timeout (if appropriate); warn users before expiry; allow “resume” from last step. |
| Missing required field | Client UX did not collect (or stripped) a mandatory input. | Enable front-end validation; add field-level hints; re-prompt user to complete required data. |
| Webhook failures | Destination endpoint is unreachable or returns non-2xx status. | Verify URL, TLS, and auth; add retries/backoff; log failures with request IDs for support. |
| Redirect URI mismatch | custom.redirect_uri differs from allow-listed domains. | Update allow list; ensure exact scheme/host/path; avoid trailing slash mismatches. |
How to debug
- Check RiskOS™ logs for API error codes and module status (e.g., OTP, KYC, DocV).
- Trace by
eval_id: Follow the evaluation through the Developer Console to see each enrichment and decision. - Inspect webhook payloads: Confirm delivery status and response codes from your endpoint.
- Verify inputs: Ensure required fields (e.g., phone, DOB) are present and properly formatted before initiating the flow.
- Reproduce in Sandbox: Use known-good payloads to isolate config vs. data issues.
Fallback strategies
- Retry initiation after correcting missing/invalid inputs.
- Offer alternate verification (e.g., voice OTP or email verification) if SMS fails or user abandons.
Escalation path
- Gather context:
eval_id, full request payload, timestamps, and any webhook IDs. - Open a ticket: Email [email protected] with the above details, expected vs. actual behavior, and any relevant logs.
- Live assistance: Our Support team will triage and, if needed, escalate to specialists; we’ll schedule a live troubleshooting session when appropriate.
Updated about 1 month ago