Response Codes

This is a draft document. Please be aware that the contents are subject to change.

OperationOutcome

Note: Not all responses contain content; sometimes the HTTP status code itself carries all the meaning.
  • 2XX: Success codes
  • 4XX: Client errors
    • Where there is a content to the response, it will always be a FHIR OperationOutcome
    • When an OperationOutcome is provided, where possible a textual description of the error will be given in the diagnostics field.
      • Note: We reserve the right to change this textual description at our discretion and without warning.
    • 401 (~ authentication problem) or 403 (~ authorisation problem). These will normally return a PKB-specific code indicating the exact nature of the problem.
      • Note: We reserve the right to change the display text of the coding at our discretion. We will not change the code values without warning, so you can code against them for error handling.
  • 5XX: Server errors
    • Where there is a content to the response, it will always be a FHIR OperationOutcome

Response Codes

HTTP Status CodeConditionNotesResponse Content
200Successful search interaction Search results
 Successful read interaction Resource
400Bad requestBasic validation problem, e.g. mandatory parameter not provided, or an unknown Operation attempted.
  • OperationOutcome
    • issue[0]: BackboneElement
      • severity = error
      • code = processing
      • diagnostics = <human readable description of problem>
401Bad authenticationYou did not provide a valid access token. This condition excludes expired access tokens and invalid API sessions, which have their own error codes because they need their own specific handling.
  • OperationOutcome
    • issue[0]: BackboneElement
      • severity = error
      • code = security
      • diagnostics = You did not provide a valid access token.
      • details: CodeableConcept
        • coding[0]: Coding
          • system = http://pkb.io/fhir/CodeSystem/response-code
          • code = BAD_AUTHENTICATION
          • display = Valid access token not provided
 Access token expired 
  • OperationOutcome
    • issue[0]: BackboneElement
      • severity = error
      • code = security
      • diagnostics = This access token expired at <timestamp>
      • details: CodeableConcept
        • coding[0]: Coding
          • system = http://pkb.io/fhir/CodeSystem/response-code
          • code = ACC_TOKEN_EXPIRED
          • display = Access token expired
 Invalid API sessionReasons an API session might be invalid:
  • It has expired
  • A refresh token was used more than once
  • OperationOutcome
    • issue[0]: BackboneElement
      • severity = error
      • code = security
      • diagnostics = This API session has expired, or has been otherwise invalidated.
      • details: CodeableConcept
        • coding[0]: Coding
          • system = http://pkb.io/fhir/CodeSystem/response-code
          • code = INVALID_API_SESSION
          • display = Invalid API session
403User type not permitted 
  • OperationOutcome
    • issue[0]: BackboneElement
      • severity = error
      • code = security
      • diagnostics = This operation requires a user type of: <permitted user types>. Your connection is of user type: <authenticated user type>
      • details: CodeableConcept
        • coding[0]: Coding
          • system = http://pkb.io/fhir/CodeSystem/response-code
          • code = USER_TYPE_NOT_PERM
          • display = User type not permitted
 No association
  • OperationOutcome
    • issue[0]: BackboneElement
      • severity = error
      • code = security
      • diagnostics = You have no association with this data.
      • details: CodeableConcept
        • coding[0]: Coding
          • system = http://pkb.io/fhir/CodeSystem/response-code
          • code = NO_ASSOCIATION
          • display = No association
 Sharing disabled
  • OperationOutcome
    • issue[0]: BackboneElement
      • severity = error
      • code = security
      • diagnostics = Sharing has been disabled for this medical record.
      • details: CodeableConcept
        • coding[0]: Coding
          • system = http://pkb.io/fhir/CodeSystem/response-code
          • code = SHARING_DISABLED
          • display = Sharing disabled
 No decryption key 
  • OperationOutcome
    • issue[0]: BackboneElement
      • severity = error
      • code = security
      • diagnostics = No decryption key is available for this medical record.
      • details: CodeableConcept
        • coding[0]: Coding
          • system = http://pkb.io/fhir/CodeSystem/response-code
          • code = NO_DECRYPT_KEY
          • display = No decryption key
 No consent
  • OperationOutcome
    • issue[0]: BackboneElement
      • severity = error
      • code = security
      • diagnostics = You have not been granted the required privacy label to see this data, and BTG is not active.
      • details: CodeableConcept
        • coding[0]: Coding
          • system = http://pkb.io/fhir/CodeSystem/response-code
          • code = NO_CONSENT
          • display = No consent
404Resource type not supported
  • OperationOutcome
    • issue[0]: BackboneElement
      • severity = error
      • code = processing
      • diagnostics = <indicates supported resources>
 Resource not found for read interaction
  • OperationOutcome
    • issue[0]: BackboneElement
      • severity = error
      • code = not-found
      • diagnostics = Could not find <resource type> with ID=[<id>]
405Method not allowed None
415Unsupported media type Simple error message
500Internal server errorFor this condition only, the diagnostics field will not be returned on production servers. This is because it might contain sensitive information.
  • OperationOutcome
    • issue[0]: BackboneElement
      • severity = error
      • code = exception
      • diagnostics = <best efforts textual description>


Comments