Error Codes
All error responses return JSON:
{
"error": "session_expired",
"message": "Your session has expired. Please relaunch the application.",
"status": 401
}
Client errors (4xx)
| Code | HTTP | When | Remediation |
|---|---|---|---|
session_not_found | 401 | No SmartLaunchContext in session | Redirect to /launch |
session_expired | 401 | Access token expired and refresh failed | Redirect to /launch |
insufficient_scope | 403 | Required SMART scope not granted | Request additional scopes |
patient_not_found | 404 | FHIR Patient resource does not exist | Check patient ID |
fhir_error | 502 | Epic FHIR returned an error | See details field for FHIR OperationOutcome |
Launch errors (redirect parameters)
Errors during the SMART launch redirect to /launch?error=...:
| Error | When |
|---|---|
discovery_failed | Could not fetch /.well-known/smart-configuration |
invalid_state | CSRF state mismatch on callback |
token_exchange_failed | Epic rejected the authorization code |
oidc_validation_failed | id_token validation failed |
session_expired | Refresh token expired — full re-launch needed |