Oracle Cloud Infrastructure Documentation

Troubleshooting

Use troubleshooting information to identify and address common issues that can occur while working with Device Data FHIR Service.

See also Device Data FHIR Service FAQs.

User Policies

Troubleshoot missing IAM policies and DDFS OAuth scopes for common DDFS Console, API, metrics, work request, and subscription tasks.

A user can't list, create, update, move, or delete DDFS instances; view work requests; query metrics; or create and monitor FHIR subscriptions. The Console or API might return an authorization, forbidden, unauthorized, or permission denied message.

Cause

The user's group, application, or service principal doesn't have the required access for the resource, compartment, or operation. DDFS uses OCI IAM policies for service resources such as instances, work requests, metrics, and Vault secrets. DDFS uses OCI Identity Domains OAuth scopes for FHIR data-plane resources such as Subscription and SubscriptionTopic.

Remedy

Ask an administrator to compare the failed operation, compartment, and caller against the policy and scope requirements.

Required access by task
Task Required access Reference
DDFS instances Use ddfs-instance-family for broad access, or ddfs-instance for instance-only access. inspect lists instances, read gets instance details, use updates instances, and manage creates, deletes, or moves instances. DDFS instance policies
Work requests Use ddfs-instance-family or ddfs-work-request. inspect lists work requests, errors, and logs; read gets work request details; manage cancels work requests. DDFS work request policies
Metrics Grant the user's group permission to read metrics in the compartment that contains the DDFS instance: Allow group <group-name> to read metrics in compartment <compartment-name>. Policies and metrics reference
FHIR subscriptions Grant the client application DDFS OAuth scopes for the subscription resources it calls, such as ddfssystem/Subscription.* and ddfssystem/SubscriptionTopic.*. If a subscription uses an OCI Vault secret for outbound authorization, also grant the DDFS service access to read the secret. Authentication and scopes, Subscription OCI Vault secret extension, and subscription authorization-secret policy
  1. Capture the exact operation, API endpoint or Console page, compartment, region, response code, error text, and request identifier.
  2. Determine whether the failure is for an OCI service resource or a FHIR data-plane request. For OCI service resources, check IAM policies. For FHIR requests, check the OAuth token issuer, audience, and DDFS scopes.
  3. Verify that the user is in the IAM group named in the policy, and that the policy is written for the compartment that contains the DDFS resource or metrics.
  4. Compare the failed operation with Device Data FHIR Service Policies and Permissions. Add the least-privilege verb or permission that covers the operation.
  5. For subscription failures, verify the client requested a fresh access token after scope changes and that the token contains the canonical system/... scope values required by the subscription or subscription topic operation.
  6. Retry the operation after policy or scope updates. If the error persists, check Audit or Logging Search for denied requests and confirm that the request is targeting the expected compartment and region.

Authorization Errors

Troubleshoot 401 and 403 responses from DDFS FHIR APIs.

A DDFS FHIR API request returns a 401 or 403 response.

Cause

The access token is missing, expired, has the wrong issuer or audience, or does not include a supported DDFS FHIR authorization scope. DDFS does not support SMART user/..., patient/..., or launch context scopes for FHIR resource authorization.

Remedy

Confirm the OCI Identity Domains resource server, client application, audience value, and DDFS scopes are configured correctly.

  1. Verify that the token issuer, tenant issuer, and audience match the DDFS deployment configuration.
  2. Verify that the token contains the canonical DDFS resource scopes required by the request, such as system/Patient.rs or system/Observation.read. Client grants and token requests use the corresponding prefixed values, such as ddfssystem/Patient.rs or ddfssystem/Observation.read.
  3. Remove unsupported SMART launch, user, or patient scopes from DDFS FHIR authorization examples and client requests.
  4. For scope syntax, the fixed ddfs client-facing prefix, token audience validation, and hard-delete requirements, see Reference: Authentication and Scopes.

Resource Status Codes

Troubleshoot common FHIR API response status codes.

A DDFS FHIR API call returns an unexpected status code.

Cause

The request can fail because of authentication, authorization, validation, unsupported operation, or resource-state errors.

Remedy

StatusDescription or How to Fix
200Successful read, search, update, or operation that returns a response body.
201Successful resource creation.
204Successful delete with no response body.
400Invalid request syntax, parameters, or payload.
401Missing, expired, or invalid OAuth access token.
403Token is valid, but it does not authorize the requested FHIR resource operation.
404Read, history, or hard-delete for missing resources.
405An update target does not exist, and update-create is not supported.
410The requested resource has been deleted.
422Business-rule validation failed, such as no matching subscription trigger.
500The service returned an internal error.