Common Issues
Authentication Token Issues
Failed to generate token
Failed to generate token
Problem: Backend returns an error when calling Doshi API.Possible Causes:
- Invalid API key
- API key not provided in Authorization header
- Invalid request parameters
- Network connectivity issues
- Verify API key:
- Check environment variables:
- Validate request parameters:
- Check API response:
Token expired or invalid
Token expired or invalid
Problem: Token is rejected by the iframe.Possible Causes:
- Token was generated too long ago
- Token was already used
- Token format is incorrect
- Generate token immediately before use:
- Donโt reuse tokens:
- Verify token format:
API key exposed in frontend
API key exposed in frontend
Problem: API key is visible in client-side code.Danger: Anyone can steal your API key and impersonate your application.Solution:
- Move API calls to backend:
- Create backend endpoint:
postMessage Issues
Messages not being received
Messages not being received
Problem: The iframe is not receiving messages from the parent window.Solutions:
- Verify origin:
- Check iframe is loaded:
- Verify message format:
- Check for JavaScript errors:
Origin mismatch errors
Origin mismatch errors
Problem: Messages are rejected due to origin mismatch.Solutions:
- Log actual origins:
- Check for trailing slashes:
- Handle multiple environments:
PING not received
PING not received
Problem: Parent window never receives PING from iframe.Solutions:
- Check iframe URL:
- Wait for iframe to load:
- Check for errors in iframe:
Query Parameter Issues
Parameters not appearing in URL
Parameters not appearing in URL
Problem: Query parameters are missing from the iframe URL.Solutions:
- Debug URL construction:
- Check for undefined values:
URL too long
URL too long
Problem: URL exceeds browser limits (typically 2000 characters).Solutions:
- Check URL length:
- Reduce parameter size:
- Switch to postMessage:
Special characters breaking URL
Special characters breaking URL
Problem: Special characters not encoding properly.Solutions:
- Use URLSearchParams:
- Verify encoding:
2FA Issues
OTP screen not showing
OTP screen not showing
Problem: 2FA is enabled but OTP screen doesnโt appear.Solutions:
- Verify 2FA flag:
- Check all required fields:
- Verify organization has 2FA enabled:
OTP not received
OTP not received
Problem: User doesnโt receive the OTP code.Solutions:
- Verify phone number:
- Check OTP channel:
- Wait and retry:
OTP verification failing
OTP verification failing
Problem: Correct OTP code is rejected.Solutions:
- Check OTP expiration:
- Verify user details match:
Browser Compatibility
postMessage not working in older browsers
postMessage not working in older browsers
Problem: postMessage API not supported.Solution:
URLSearchParams not available
URLSearchParams not available
Problem: URLSearchParams not supported in older browsers.Solution:
Iframe not loading on iOS Safari
Iframe not loading on iOS Safari
Problem: Iframe doesnโt load on iOS Safari.Solutions:
- Check iframe attributes:
- Ensure HTTPS:
Mobile WebView Issues
Content not visible when keyboard opens
Content not visible when keyboard opens
Problem: When keyboard opens, content gets squeezed and becomes not visible.Solution: Handle keyboard visibility in your app wrapper.iOS:Android:See Best Practices - Mobile Integration for complete code.
User can zoom and breaks layout
User can zoom and breaks layout
Problem: Users can pinch-to-zoom and it breaks the layout.Solution: Disable zoom in your WebView.Web:iOS:Android:See Best Practices - Disable Zoom for details.
Links don't open from iframe
Links don't open from iframe
Problem: External links clicked in Doshi Frontend donโt open.Cause: Popups are blocked for security reasons.Solution: Implement postMessage callback to handle link clicks.See Best Practices - Handling Link Clicks for platform-specific implementations.
WebView not loading on mobile
WebView not loading on mobile
Problem: Doshi Frontend doesnโt load in mobile WebView.Solutions:
- Enable JavaScript:
- Check HTTPS:
- Ensure youโre loading
https://embed.doshi.app - iOS requires HTTPS by default (App Transport Security)
- Check App Permissions:
Network Issues
Slow authentication
Slow authentication
Problem: Authentication takes too long.Solutions:
- Add timeout:
- Show loading state:
- Preconnect to domain:
Intermittent failures
Intermittent failures
Problem: Authentication works sometimes but fails randomly.Solutions:
- Implement retry logic:
- Check network status:
IP Whitelisting Issues
403 Forbidden Error
403 Forbidden Error
Problem: Receiving 403 Forbidden when calling Doshi API.Cause: Your server IP is not whitelisted.Solution:
- Find your server IP:
-
Email [email protected] with:
- Your organization name
- Your server IP address
- Whether itโs for production or staging
- Wait for confirmation that your IP is whitelisted
Works in one environment, not another
Works in one environment, not another
Problem: API works in staging but not production (or vice versa).Cause: Different servers have different IPs.Solution:Get the IP from each server and have all of them whitelisted:Contact [email protected] with all IPs.
Debugging Tools
Enable Debug Logging
Message Inspector
Network Monitor
Check iframe Status
Testing Checklist
Test with valid credentials
Test with invalid credentials
Test with missing token
Test with expired token
Test 2FA flow (if enabled)
Test on Chrome
Test on Firefox
Test on Safari
Test on Edge
Test on mobile Safari (iOS)
Test on mobile Chrome (Android)
Test with slow network (throttling)
Test with offline/online transitions
Test timeout scenarios
Test error recovery
Getting Help
If youโre still experiencing issues after trying these solutions:Contact Support
Email us at [email protected] with:
- Detailed description of the issue
- Browser and OS information
- Any error messages
- Steps to reproduce
Check API Status
Verify Doshi services are operational
Quick Fixes Reference
| Issue | Quick Fix |
|---|---|
| Messages not received | Check event.origin validation |
| Token not working | Generate fresh token, donโt reuse |
| API key exposed | Move to backend immediately |
| URL too long | Switch to postMessage |
| 2FA not showing | Verify is2FaEnabled: true and all required fields |
| Slow loading | Add preconnect, implement timeout |
| Origin mismatch | Log and compare actual vs expected origins |
| CORS errors | Ensure all URLs use HTTPS |
| Iframe not loading | Check src attribute and network tab |
