Application-Specific Errors

Beyond generic HTTP errors and system notifications, the Revenue Recovery platform has errors specific to its features and workflows. This guide organizes troubleshooting by feature area and deployment model, helping you quickly resolve issues related to EHR connectivity, authentication, data processing, and other platform-specific functionality.

Deployment Model Considerations

Your troubleshooting approach varies based on your deployment model. Understanding who manages each component helps determine escalation paths:

Responsibility Matrix

⚠️ Important: The Relay Service is always provided and managed by the customer, regardless of deployment model. It runs in your environment to facilitate secure communication between the Revenue Recovery platform and your EHR system.

When to Contact Support

SaaS Deployment:

• Contact Ailevate support for platform, database, or application-level errors
• Contact your IT team for EHR credentials, network connectivity, firewall rules, and Relay Service issues

On-Premise Deployment:

• Contact Ailevate support for application logic, software bugs, or configuration guidance
• Contact your IT team for infrastructure, hardware, EHR credentials, network, Relay Service, and database issues

---

EHR Connection Errors

EHR connection errors occur when the platform cannot successfully communicate with your Electronic Health Record system to retrieve claims data.

Connection Error Quick Reference

Connection Failed (General)

Symptom: "Connection failed" toast notification or error message during EHR connection test.

Possible Causes:

• Network connectivity issue between platform and EHR server
• Firewall blocking outbound connections on required port (typically 1433 for SQL)
• Invalid or expired EHR credentials
• Insufficient permissions on EHR database account
• EHR system temporarily unavailable or under maintenance
• Incorrect server address or connection string
• Relay Service not running or unreachable

Resolution Steps:

1. Verify Relay Service status (always required):

   • Confirm Relay Service is running on your infrastructure
   • Check Relay Service logs for connection attempts and errors
   • Verify network connectivity between Relay Service and EHR server
   • Restart Relay Service if needed

2. Navigate to EHR Connections and click "Test Connection"

3. Verify network connectivity:

   • Confirm firewall rules allow outbound connections on port 1433
   • Check that Relay Service can reach EHR server
   • Verify no network routing issues

4. Check EHR credentials:

   • Verify username and password are correct
   • Confirm password hasn't expired
   • Test credentials by logging into EHR system directly if possible

5. Verify EHR system status:

   • Contact your EHR administrator to confirm system is operational
   • Check for scheduled maintenance windows

6. Review detailed logs:

   • Navigate to Logs and Monitoring for specific error details
   • Look for connection timeout, authentication failure, or permission errors

7. Verify connection configuration:

   • Double-check server address, database name, port number
   • Ensure connection string format is correct

Escalation:

• Customer IT: Relay Service, network, firewall, EHR credentials
• Ailevate Support: Configuration guidance, platform-side issues

See also: Linking to Internal Systems for EHR connection setup.

---

Authentication Errors (EHR)

Symptom: "Authentication failed" or "Login failed for user" during EHR connection.

Possible Causes:

• Incorrect username or password
• Password expired and needs reset
• SQL account locked or disabled
• Authentication method mismatch (Windows vs. SQL authentication)

Resolution Steps:

1. Verify credentials are entered correctly (check for typos)
2. Confirm password hasn't expired:
   • Check with your EHR administrator
   • Reset password if expired
3. Verify SQL account status:
   • Ensure account is active and not locked
   • Check that account hasn't been disabled
4. Confirm authentication method:
   • Verify whether Windows Authentication or SQL Server Authentication is required
   • Ensure connection string matches authentication type
5. Test credentials directly:
   • Try connecting to SQL Server using SQL Server Management Studio with the same credentials
   • If direct connection fails, resolve the credential issue at the EHR level first

Responsibility: Customer IT manages EHR credentials and SQL accounts

---

Permission Errors (EHR)

Symptom: "Permission denied" when accessing EHR data, or "User does not have permission" errors.

Possible Causes:

• SQL account lacks READ permissions on required databases
• Missing permissions on specific tables needed for claims data
• Database role membership insufficient
• Server-level permissions not granted

Resolution Steps:

1. Work with your EHR administrator to verify SQL account permissions
2. Ensure the account has:
   • READ access to the claims/billing database
   • SELECT permissions on all required tables
   • CONNECT permission to the database server
   • Appropriate database role membership (typically db_datareader)
3. Test permissions:
   • Run Test Connection to see specific permission errors
   • Review logs for tables or databases mentioned in permission errors
4. Grant minimum necessary permissions:
   • Platform requires READ-only access
   • No write, update, or delete permissions needed
   • Follow principle of least privilege

Responsibility: Customer EHR administrator grants database permissions

ℹ️ Note: Ailevate does not manage or troubleshoot EHR credentials, permissions, or database access. These are customer-managed components. Ailevate provides guidance on required permissions and configuration.

---

Test Connection Failures

Symptom: Test Connection returns failure status on EHR Connections page.

Possible Causes:

• Any of the connection, authentication, or permission issues above
• Relay Service not running or unreachable
• Network timeout due to slow connection or high latency
• Port blocking by firewall or security software

Resolution Steps:

1. Check Configuration > Status page for EHR connection health indicators
2. Verify Relay Service status (always required):
   • Confirm Relay Service is running
   • Check Relay Service logs for errors
   • Verify network connectivity between Relay Service and EHR server
   • Test Relay Service independently before platform connection
3. Check for timeout issues:
   • Test during off-peak hours to rule out performance issues
   • Increase timeout settings if connection is slow but functional
4. Review firewall logs:
   • Verify no blocked connection attempts
   • Check both local and network firewalls
5. Systematic testing:
   • Test basic network connectivity (ping server if possible)
   • Test port connectivity (telnet to port 1433)
   • Test authentication (direct SQL connection)
   • Finally test through Revenue Recovery platform

---

Data Sync Errors

Symptom: "Data sync failed" notification, or EHR data not appearing in platform despite successful connection.

Possible Causes:

• Connection interruption during sync process
• Data format changes in EHR database schema
• Data volume exceeding timeout thresholds
• EHR database locked or in maintenance mode during sync
• Specific data records with formatting issues

Resolution Steps:

1. Run Test Connection to verify basic connectivity
2. Check sync schedule and timing:
   • Verify sync isn't conflicting with EHR maintenance windows
   • Review sync logs for timing of failures
3. Review sync logs for specific errors:
   • Look for table or field names in error messages
   • Identify if sync fails on specific data vs. general failure
4. Verify EHR schema hasn't changed:
   • Work with EHR administrator to confirm no recent database changes
   • Check if table or column names were modified
5. Check data volume and sync scope:
   • Verify sync isn't timing out due to large data volume
   • Consider adjusting sync frequency or scope if needed
6. Test manual sync during off-peak hours

Escalation:

• Customer IT/EHR Admin: Schema changes, maintenance windows, data quality
• Ailevate Support: Sync logic issues, timeout adjustments, data transformation problems

---

Authentication System Errors

Authentication errors occur when you're trying to log in or when your session credentials are invalid.

MagicLink Errors

Email Not Received

Symptom: After requesting a MagicLink login, you don't receive the email with the login link.

Possible Causes:

• Email in spam/junk folder
• Email address typo when requesting link
• Email server blocking messages from Revenue Recovery
• Email delivery delay

Resolution Steps:

1. Check spam/junk folder thoroughly
2. Wait 5-10 minutes for email delivery (occasional delays)
3. Verify you entered correct email address
4. Check with IT department:
   • Confirm email server isn't blocking sender
   • Add Revenue Recovery sending domain to allow list
5. Request a new MagicLink with verified email address
6. Try alternative email address if available

---

Link Expired

Symptom: Clicking MagicLink shows "Link expired" or "Invalid token" error.

Possible Causes:

• MagicLink expired due to time limit (typically 15-30 minutes)
• Link was already used (single-use security feature)
• System clock on your device significantly incorrect

Resolution Steps:

1. Request a new MagicLink
2. Use the new link promptly (within 15-30 minutes)
3. Verify system time on your device is correct
4. Don't click the same link multiple times
5. If links consistently expire before you can use them, contact administrator about timeout settings

---

Invalid Token

Symptom: "Invalid token" or "Authentication failed" when clicking MagicLink.

Possible Causes:

• Link was tampered with or corrupted
• Link was copied incorrectly
• Email client modified the URL
• Link already used

Resolution Steps:

1. Request a new MagicLink
2. Click the link directly from email (don't copy/paste if possible)
3. If you must copy the link, ensure entire URL is copied
4. Try opening link in different browser
5. Clear browser cache and cookies before trying again

See also: Configuring Authentication for MagicLink setup and troubleshooting.

---

Microsoft EntraID OAuth Errors

Consent Required

Symptom: "Admin consent required" or "Consent not granted" during OAuth flow.

Possible Causes:

• Application requires administrator consent to access organization directory
• Initial consent not yet granted by EntraID administrator
• Consent was revoked

Resolution Steps:

1. Contact your Microsoft EntraID administrator
2. Administrator must grant consent for Revenue Recovery application
3. Once consent granted, retry authentication
4. All users in organization should then be able to authenticate

---

Invalid Redirect URI

Symptom: "Redirect URI mismatch" or "Invalid redirect" error during OAuth flow.

Possible Causes:

• OAuth application configuration mismatch between EntraID and Revenue Recovery
• Redirect URI not properly registered in EntraID app registration
• Multiple environments with different redirect URIs

Resolution Steps:

1. This is a configuration issue requiring administrator intervention
2. Administrator should verify:
   • Revenue Recovery redirect URI matches EntraID app registration exactly
   • Redirect URI includes correct protocol (https://)
   • No trailing slashes or URL differences
3. Configuration must match on both sides
4. After configuration correction, retry authentication

---

Token Errors

Symptom: "Token expired," "Invalid token," or "Token revoked" errors.

Possible Causes:

• OAuth access token expired (typical 1-hour lifespan)
• Refresh token expired or revoked
• User password changed in EntraID
• User account disabled or permissions changed
• Administrator revoked application access

Resolution Steps:

1. Close browser and clear cache/cookies
2. Re-authenticate by clicking "Sign in with Microsoft"
3. If error persists, try incognito/private browser window
4. Verify your EntraID account is active and not locked
5. Check with administrator if application access was revoked
6. If persistent, administrator should verify OAuth application configuration in EntraID

See also: Configuring Authentication for EntraID OAuth setup and troubleshooting.

---

Session Token Errors

Multi-Factor Authentication Errors

Symptom: MFA code rejected, expired, or not received.

Possible Causes:

• Code expired (typically 30-60 second validity)
• Device time not synchronized correctly
• Wrong code entered
• MFA device lost or unavailable

Resolution Steps:

1. Ensure device time is correctly synchronized
2. Wait for new code to generate if previous expired
3. Enter code carefully (no spaces, correct digits)
4. If using authenticator app, verify it's the correct account
5. If device lost or unavailable, contact administrator to reset MFA

---

Security Policy Errors

Security policy errors occur when actions are blocked by your organization's security settings.

IP Address Blocked (IP Allow List)

Symptom: "Access denied - IP not allowed" or 403 Forbidden error with IP-related message.

Possible Causes:

• Your current IP address not in the IP Allow List
• VPN changed your IP address to non-allowed IP
• Working from new location with different IP
• IP Allow List recently enabled or modified

Resolution Steps:

1. Identify your current IP address (visit whatismyip.com or similar)
2. Verify whether IP Allow List is enabled for your organization
3. Options to resolve:
   • If administrator: Add your IP address to Allow List in Security Settings
   • If user: Contact administrator to add your IP or IP range to Allow List
4. If using VPN:
   • Verify VPN exit IP is in Allow List
   • Consider disconnecting VPN if organization policy allows
5. For mobile/changing IPs:
   • Request administrator add IP range rather than specific IP
   • Discuss whether IP Allow List should include broader ranges for remote users

⚠️ Important: IP Allow List is a security feature. Don't request it be disabled without considering security implications. Instead, ensure legitimate IPs are included.

See also: Security Settings for IP Allow List management.

---

Domain Not Trusted (Trusted Domain List)

Symptom: "Domain not trusted" error when attempting email-based features or account activation.

Possible Causes:

• User email domain not in Trusted Domain List
• Trusted Domain List enabled without configuring domains
• Attempting to create account with non-approved email domain

Resolution Steps:

1. Verify your email domain (e.g., @example.com)
2. Contact administrator to:
   • Add your domain to Trusted Domain List
   • Verify domain ownership if required
3. Administrator should:
   • Navigate to Security Settings > Advanced Settings
   • Add domain to Trusted Domain List
   • Verify domain is spelled correctly (no typos)
4. Once added, retry your action

See also: Security Settings for Trusted Domain configuration.

---

Session Timeout Errors

Symptom: Frequent "Session expired" messages requiring re-login.

Possible Causes:

• Session timeout setting too short for your workflow
• Working across long periods without interaction
• Multiple concurrent sessions causing conflicts

Resolution Steps:

1. Check current session timeout setting in Security Settings
2. Evaluate if timeout is appropriate:
   • Healthcare compliance may require shorter timeouts
   • Balance security with user productivity
3. Options to address:
   • Administrator can extend session timeout in Security Settings
   • Keep platform tab active and interact periodically
   • Save work frequently to avoid loss from unexpected timeout
4. Avoid multiple concurrent sessions (log out of unused sessions)

See also: Security Settings for session timeout configuration.

---

Data Processing Errors

Data processing errors occur when submitted data doesn't meet validation requirements or causes processing issues.

Common Validation Errors

Processing Timeout Errors

Symptom: "Processing timeout" or "Request timed out" during long-running operations.

Possible Causes:

• Large dataset exceeding processing time limit
• System busy during peak usage
• Network interruption during processing
• Complex calculation or report generation

Resolution Steps:

1. Reduce scope of operation:
   • Smaller date range
   • Fewer records
   • Simpler report parameters
2. Retry during off-peak hours (early morning, late evening)
3. Verify network connection stability
4. For reports/exports:
   • Break into smaller chunks
   • Export incrementally rather than all at once
5. If timeouts persist with reasonable scope, contact support with:
   • What operation was timing out
   • Scope/size of data involved
   • Time of day attempted

---

Export and Report Generation Errors

Export errors occur when attempting to generate PDF reports or export data from the platform.

Export Error Quick Reference

Export Troubleshooting Steps

1. Reduce date range:

   • Try weekly instead of monthly
   • Export one month at a time instead of quarter/year

2. Verify export permissions:

   • Check your role includes export capability
   • Contact administrator if export permission missing

3. Retry timing:

   • Try during off-peak hours (early morning, weekends)
   • Avoid end-of-month periods when usage typically peaks

4. Check network:

   • Verify stable internet connection
   • Large exports may take several minutes

5. Systematic troubleshooting:

   • Try exporting single claim to verify basic functionality
   • Gradually increase scope to identify threshold
   • If specific data fails, may indicate data formatting issue

Escalation: Contact [email protected] with date range, approximate number of claims, user role, time of day attempted, and any specific filters applied.

---

User and Organization Management Errors

These errors occur when managing users, roles, and organizational structure.

User Management Error Reference

See also: User Role Management for user and role management.

---

Deployment-Specific Notes

SaaS Deployment

Ailevate Manages:

• Platform infrastructure and scaling
• Database performance and backups
• Application updates and patches
• System monitoring and alerts

Customer Manages:

• Relay Service deployment and maintenance
• EHR credentials and permissions
• Network connectivity and firewall rules
• User authentication credentials
• IP Allow List and security policies

On-Premise Deployment

Ailevate Manages:

• Application code and logic
• Software updates and patches
• Configuration guidance
• Feature support

Customer Manages:

• All infrastructure (servers, network, storage)
• Relay Service deployment and maintenance
• AI Warehouse hardware and performance
• Database management and backups
• EHR credentials and permissions
• System monitoring and health checks
• Network connectivity and firewall rules
• User authentication credentials
• Security policy configuration

---

Need Help?

If you encounter application-specific errors that persist after following these troubleshooting steps:

For EHR Connection Issues:

• Contact your IT team for Relay Service, network, firewall, and credential issues
• Contact EHR administrator for database permissions and schema issues
• Contact Ailevate support for configuration guidance and platform-side troubleshooting

For Authentication Issues:

• Contact your IT team for email server, MFA, and EntraID configuration
• Contact organization administrator for user account and security policy issues
• Contact Ailevate support for platform authentication system issues

For Data Processing & Export Issues:

• Try troubleshooting steps in this guide first (reduce scope, retry timing)
• Contact organization administrator for permission-related issues
• Contact Ailevate support for persistent errors, timeouts, or data quality issues

General Support:

• Review Common Error Messages overview for escalation guidance
• Use the systematic diagnostic approaches integrated throughout this guide for complex scenarios
• Contact support through the help widget in the bottom right corner
• Email [email protected] for urgent assistance

💡 Pro Tip: When contacting support, include your deployment model (SaaS or on-premise), specific error messages, what you were attempting, and troubleshooting steps already taken. This helps route your request to the appropriate team and speeds resolution.