Swedish Healthcare Service - Health Condition Description
0.1.0 - CI Build Sweden

Swedish Healthcare Service - Health Condition Description - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Error Codes

Error Codes and Handling

This page documents all error codes used in the Health Condition Description service domain.

Error Response Structure

All services return a result element containing:

<result>
  <resultCode>ERROR_CODE</resultCode>
  <message>Human-readable error description</message>
  <errorId>Optional unique error identifier</errorId>
  <logId>Optional log reference for troubleshooting</logId>
</result>

Result Codes

SUCCESS

Code Description
OK Request processed successfully with data returned
INFO Request processed successfully but informational message included
NO_DATA_FOUND Request successful but no data matches search criteria

APPLICATION_ERROR

Logical errors in request processing.

Code Description Resolution
INVALID_REQUEST Request violates business rules Check: datePeriod ordering, required fields, value formats
VALIDATION_ERROR Data validation failed Verify all field values against specifications
ACCESS_DENIED Caller not authorized to access requested data Check: PDL permissions, blocking status, consent
PATIENT_NOT_FOUND Patient identifier not recognized Verify patient ID and OID are correct
NO_CONSENT Patient has not provided consent Patient must provide consent before access
BLOCKED Patient has blocked access Blocking prevents access - contact patient
NOT_APPROVED_FOR_PATIENT Data not approved for patient access Only relevant for patient-facing services
SOURCE_SYSTEM_NOT_AVAILABLE Specified source system unavailable Try again later or use aggregating service
INVALID_SOURCE_SYSTEM sourceSystemHSAId doesn't match logicalAddress Ensure consistency between addressing fields
MAX_RESULT_SIZE_EXCEEDED Result set too large Use datePeriod to limit scope, or use partial retrieval
INVALID_REFERENCE hasMoreReference invalid or expired Reference may have expired (>1 hour), restart query

TECHNICAL_ERROR

Infrastructure or system failures.

Code Description Resolution
TECHNICAL_ERROR General technical failure Check logs, retry, contact support if persists
INTERNAL_ERROR Internal system error Producer internal issue - contact producer support
TIMEOUT Request processing exceeded time limit Reduce scope or retry
TRANSFORMATION_ERROR Data transformation failed Producer issue - report to producer
DATABASE_ERROR Database access failed Temporary issue - retry

Error Handling by Component

Service Consumer

On APPLICATION_ERROR:

  • Display appropriate user message
  • Log for audit trail
  • Allow user to correct and retry

On TECHNICAL_ERROR:

  • Display generic error message
  • Log for troubleshooting
  • Implement retry logic (with backoff)

On NO_DATA_FOUND:

  • Display "no results found"
  • May be expected result

Aggregating Service

When querying multiple source systems:

Partial Success Handling:

  • If some systems succeed and others fail
  • Return SUCCESS with partial results
  • Include partial flag = true
  • List failed systems in response

Example Response:

<result>
  <resultCode>OK</resultCode>
  <message>Partial results - 2 of 3 systems responded</message>
</result>
<partial>true</partial>
<failedSources>
  <sourceSystem>SE2321000016-SYS3</sourceSystem>
  <error>TIMEOUT</error>
</failedSources>

Total Failure:

  • If all systems fail, return appropriate error
  • Use most severe error code
  • Include details of all failures

Source System

Must Return Errors For:

  • Invalid patient ID format
  • Date period errors (end before start)
  • Access control violations
  • System unavailability

Should Include:

  • logId for troubleshooting
  • Specific message for developers
  • Generic message for end users

Error Scenarios and Examples

Scenario 1: Invalid Date Period

Request:

<timePeriod>
  <start>20241231</start>
  <end>20240101</end>
</timePeriod>

Response:

<result>
  <resultCode>INVALID_REQUEST</resultCode>
  <message>timePeriod.end must be after timePeriod.start</message>
</result>

Scenario 2: Access Denied

Request: User without PDL permission attempts access

Response:

<result>
  <resultCode>ACCESS_DENIED</resultCode>
  <message>Caller does not have sufficient permissions to access patient data</message>
  <logId>AUD-2024-123456</logId>
</result>

Scenario 3: Patient Blocking

Request: Accessing blocked patient

Response:

<result>
  <resultCode>BLOCKED</resultCode>
  <message>Patient has blocked access to their information</message>
</result>

Scenario 4: Source System Mismatch

Request:

<soap:Header>
  <LogicalAddress>SE2321000016-SYS1</LogicalAddress>
</soap:Header>
<soap:Body>
  <GetCareDocumentation>
    <sourceSystemHSAId>SE2321000016-SYS2</sourceSystemHSAId>
    ...
  </GetCareDocumentation>
</soap:Body>

Response:

<result>
  <resultCode>INVALID_SOURCE_SYSTEM</resultCode>
  <message>sourceSystemHSAId must match LogicalAddress for direct queries</message>
</result>

Scenario 5: Partial Data Continuation Error

Request:

<GetCareDocumentation>
  <hasMoreReference>expired-reference-12345</hasMoreReference>
</GetCareDocumentation>

Response:

<result>
  <resultCode>INVALID_REFERENCE</resultCode>
  <message>hasMoreReference expired or invalid. Please restart query.</message>
</result>

Scenario 6: Aggregator with Partial Failure

Scenario: 3 systems queried, 2 succeed, 1 times out

Response:

<result>
  <resultCode>OK</resultCode>
  <message>Partial results returned</message>
</result>
<partial>true</partial>
<failedSources>
  <sourceSystem>SE2321000016-SYS3</sourceSystem>
  <error>TIMEOUT</error>
  <message>System did not respond within timeout period</message>
</failedSources>
<careDocumentation>
  <!-- Data from systems 1 and 2 -->
</careDocumentation>

Error Handling Best Practices

For Consumers

  1. Implement Proper Error Handling
    • Catch and handle all error codes
    • Display user-friendly messages
    • Log technical details
  2. Use Retry Logic
    • Retry on TECHNICAL_ERROR with exponential backoff
    • Don't retry APPLICATION_ERROR (except after fix)
    • Maximum 3 retry attempts
  3. Handle Partial Results
    • Check partial flag
    • Inform user of incomplete data
    • Allow user to decide if sufficient
  4. Logging
    • Log all errors with context
    • Include logId and errorId from response
    • Correlate with user actions

For Producers

  1. Be Specific
    • Use most specific error code
    • Provide actionable error messages
    • Include troubleshooting info
  2. Include Identifiers
    • Always provide logId
    • Use errorId for tracking
    • Enable support teams to investigate
  3. Distinguish Error Types
    • Use APPLICATION_ERROR for business logic
    • Use TECHNICAL_ERROR for infrastructure
    • Never expose internal details to consumers
  4. Document Custom Errors
    • Document any producer-specific error codes
    • Provide examples
    • Include in integration documentation

Troubleshooting Guide

NO_DATA_FOUND vs Empty Result

  • NO_DATA_FOUND = Query was valid but matched nothing
  • OK with no data = Also acceptable pattern
  • Both are success cases

ACCESS_DENIED vs BLOCKED

  • ACCESS_DENIED = Requester lacks permission (PDL, system authorization)
  • BLOCKED = Patient actively blocked access
  • NO_CONSENT = Patient hasn't given consent (where required)

TIMEOUT vs SOURCE_SYSTEM_NOT_AVAILABLE

  • TIMEOUT = System responded but too slowly
  • SOURCE_SYSTEM_NOT_AVAILABLE = System not reachable/down

When to Use INVALID_REQUEST

Use INVALID_REQUEST when:

  • Required field missing
  • Date period end before start
  • Invalid date format
  • sourceSystemHSAId mismatch
  • Invalid value for enumeration

When to Use VALIDATION_ERROR

Use VALIDATION_ERROR when:

  • Field format invalid (but not structural)
  • Value out of range
  • Business rule violation
  • Data integrity check failed

Error Monitoring

Metrics to Track

By Consumer:

  • Error rate per service
  • Most common error codes
  • Time to resolution

By Producer:

  • Error distribution
  • Timeout frequency
  • System availability

By Aggregator:

  • Partial failure rate
  • Per-source-system error rates
  • Average systems responding

Alerting Thresholds

Critical:

  • Error rate > 10%
  • All source systems failing
  • ACCESS_DENIED spike (potential attack)

Warning:

  • Error rate > 5%
  • Timeout rate > 2%
  • Single source system consistently failing

References