SDK API Error Handling
SDK API Error Handling Guide: OperationOutcome
Overview of OperationOutcome
The OperationOutcome is a standardized resource used to communicate the results of operations, particularly those that do not execute as expected. This resource is essential for developers as it encapsulates errors and informational messages about issues encountered during API interactions.
The OperationOutcome resource consists of one or more Issue components, each detailing a specific problem. These issues help developers understand what went wrong, why it went wrong, and how to possibly fix it. Each issue in an OperationOutcome includes the following attributes:
- Severity: Indicates the severity of the issue. (e.g.,
WARNING,INFORMATION,ERROR,FATAL).- A full list of FHIR supported Issue Severities can be found here - https://build.fhir.org/valueset-issue-severity.html
- Code: A high-level classification of the issue type (e.g.,
INVALID,VALUE,REQUIRED, etc.).- A full list of FHIR supported Issue Types can be found here - https://build.fhir.org/codesystem-issue-type.html
- Details: A human-readable explanation providing more details about the issue.
Using OperationOutcome in the b.well SDK
When an SDK API operation fails or encounters warnings, an OperationOutcome object is returned. This object includes all the necessary information to identify and resolve the issues. It's important for developers to check the OperationOutcome whenever an API does not return the expected result.
Business-Rule Issue Types
BUSINESS_RULE issues indicate that a request does not comply with specific business rules or constraints set by the system. When a business-rule issue is present, the details attribute of the OperationOutcome will contain additional information in a coding array. This array includes a code and a text value:
- code: A specific error code indicating the nature of the business-rule issue.
- text: A human-readable text intended for display to the app user, providing more context about the issue.
Developers should handle business-rule issues appropriately in their applications, ensuring that the user is informed of the issue and guided on how to correct it.
Potential Issue Types in the b.well SDK
The following tables outline potential issue types, organized by method, that could be returned via the b.well SDK.
Initialize
| IssueType | Cause | Additional Detail |
|---|---|---|
REQUIRED | ClientKey was not provided when initializing the SDK |
Authenticate
| IssueType | Cause | Additional Detail |
|---|---|---|
EXCEPTION | The SDK was not initialized prior to attempting authentication | Before attempting to authenticate with b.well you must first successfully call initialize |
VALUE | Invalid Client Key JWT could not be verified | |
SECURITY | Failure to authenticate the user |
General Errors
The following could be returned from any method after authentication has failed:
| IssueType | Cause | Additional Detail |
|---|---|---|
EXCEPTION | Authentication failed due to an invalid JWT or some other reason | The TokenRepository contains a null access token, an authentication is required |
getProfile
| IssueType | Cause | Additional Detail |
|---|---|---|
NOT_FOUND | Client user/person ID was not found |
updateProfile
getConsents
| IssueType | Cause | Additional Detail |
|---|---|---|
EXCEPTION | Consent search failed |
createConsents
| IssueType | Cause | Additional Detail |
|---|---|---|
EXCEPTION | Unknown consent category passed into createConsent Consent could not be created | |
REQUIRED | OrganizationId was not provided when creating consent of category: PROA_ATTESTATION | |
VALUE | OrganizationId is invalid |
registerDevice
| IssueType | Cause | Additional Detail |
|---|---|---|
REQUIRED | Platform or name are not present in the request | |
VALUE | Platform name is invalid or not recognized |
getTasks
| IssueType | Cause | Additional Detail |
|---|---|---|
NOT_SUPPORTED | Task sort method is not recognized | |
VALUE | The specified pageSize or page value is invalid |
updatedTaskStatus
| IssueType | Cause | Additional Detail |
|---|---|---|
INVALID | TaskId or task status is missing Task status is not valid | |
NOT_FOUND | Task could not be found with provided TaskId | |
BUSINESS_RULE | Unsupported task status | UNSUPPORTED_STATUS The new task status provided is not supported |
BUSINESS_RULE | Transition from current task status to new task status is not supported | UNSUPPORTED_STATE_CHANGE For example, task status cannot be changed from COMPLETED to IN_PROGRESS |
searchProviders, searchConnections
| IssueType | Cause | Additional Detail |
|---|---|---|
VALUE | Unsupported enum value was passed in the request The specified pageSize or page value is invalid | |
EXCEPTION | An unexpected internal error has occurred |
requestConnection
| IssueType | Cause | Additional Detail |
|---|---|---|
EXCEPTION | An unexpected internal error has occurred |
getDataSource
| IssueType | Cause | Additional Detail |
|---|---|---|
NOT_FOUND | The connection passed in the request does not exist |
createConnection
| IssueType | Cause | Additional Detail |
|---|---|---|
SECURITY | The user entered invalid credentials while making the connection | |
TIMEOUT | The request to the external connection service timed out | |
VALUE | Invalid connectionId was passed in the request | |
EXCEPTION | An unexpected internal error has occurred |
disconnectConnection
| IssueType | Cause | Additional Detail |
|---|---|---|
NOT_FOUND | User is not connected to the connection that is being requested for disconnection |
getOauthUrl
| IssueType | Cause | Additional Detail |
|---|---|---|
EXCEPTION | Portal redirect URL is not configured Could not generate authorization URL for OAuth flow | |
NOT_FOUND | Could not get redirect URL for the connection |
get[ResourceGroups]
| IssueType | Cause | Additional Detail |
|---|---|---|
VALUE | Unsupported field in the request input Non-string value assigned to string field Non-boolean value assigned to boolean field Non-integer value assigned to integer field Non-date value assigned to a date field Invalid pageSize or page | |
EXCEPTION | Misspelled or unsupported field in request |
get[BaseResources]
| IssueType | Cause | Additional Detail |
|---|---|---|
VALUE | Unsupported field in the request input Non-integer value assigned to integer field Invalid pageSize or page |
getLabKnowledge, getMedicationKnowledge
| IssueType | Cause | Additional Detail |
|---|---|---|
VALUE | Unsupported field in the request input Non-ID value assigned to ID field Non-integer value assigned to integer field Invalid pageSize or page |
getHealthSummary
| IssueType | Cause | Additional Detail |
|---|---|---|
VALUE | Unsupported field in the request input |
Updated about 2 months ago