Kanta rajapinnan virhevastaus

Kanta-palveluiden FHIR-rajapinnat vastaavat virhetilanteissa virhevastauksen, jossa on mukana http virhestatuskoodi ja mahdollinen OperationOutcome -resurssi.

Virhevastauksen paluukoodeissa noudatetaan FHIR standardin RESTful-määrittelyissä annettuja ohjeita paluukoodien käytöstä (ks. tarkemmin FHIR RESTful API). Tunnistautumisen ja käyttöoikeustarkastusten virheistä palvelu vastaa ensisijaisesti http virhekoodeilla 401 ja 403. Palvelu voi palauttaa näissäkin tilanteissa vastauksen http body osassa lisätietoja OperationOutcome-resurssilla, jos se on mahdollista. Tunnistamiseen OAuth2.0 protokollaa käyttävissä rajapinnoissa vastataan sen sijaan OAuthin mukainen virhevastaus, joka on dokumentoitu palveluiden auktorisointioppaaseen.

OperationOutcome-resurssi palautetaan http body osan sisällä ja se sisältää tarkemmat virheilmoitukset. Kanta-palveluissa käytettävää OperationOutcome-resurssia ei ole profiloitu. OperationOutcome-resurssissa on mukana yksi tai useampi issue-elementti ja näistä yhdessä on ilmaistu koodiston Kanta-palvelut - Prosessivirheet ja huomautukset (1.2.246.537.5.40112.2006) mukainen virhekoodi. Koodisto on käytössä myös muissa Kanta-palveluiden rajapinnoissa ja sen vastauskoodien merkitys ei muutu FHIR-rajapinnan myötä. Tämän lisäksi palvelu saattaa vastata useita muita issue-tietueita, esimerkiksi validoinnissa nousevista huomioista, näissä ei ole mukana Kanta-palvelut - Prosessivirheet ja huomautukset koodiston mukaista koodia.

OperationOutcome-resurssin issue-elementin alaisia tietoja käytetään virhevastauksissa seuraavasti:

  • severity saa arvon ”error”
    • muiden koodien tarve arvioidaan myöhemmin
  • code saa arvon IssueType ValueSet:stä
    • tämän perusteella lähettävä pää voi päätellä minkä tyyppisestä virheestä on kyse (onko virhe lähettävässä päässä, vai vastaanottavassa päässä ja voiko pyynnön lähettää uudelleen sellaisenaan vai vaatiiko se huomiota ennen uudelleen lähettämistä)
    • aluksi code saa useassa palvelussa arvon ”processing” mutta eri koodien käyttö tarkennetaan myöhemmin
  • details -elementin tietotyyppi on CodeableConcept ja se rakentuu Coding -tietotyypistä ja text -elementistä (text -elementtiä ei käytetä palautettavassa virhevastauksessa), coding -tietotyypin elementeissä tiedot annetaan seuraavasti:
    • system -elementissä virheiden ilmoittamisessa käytettävä koodisto, Kanta-palvelut - Prosessivirheet ja huomautukset koodiston osalta annetaan arvo: urn:oid:1.2.246.537.5.40112.2006
    • code -elementissä varsinainen virhekoodi, Kanta-palvelut - Prosessivirheet ja huomautukset osalta annetaan kyseisen koodiston arvo
    • display elementissä virhekoodia vastaava selite, Kanta-palvelut - Prosessivirheet ja huomautukset – koodiston mukaisesti
  • diagnostics -elementillä voidaan palauttaa virheen tarkempi kuvaus

Esimerkki Kanta-palvelut - Prosessivirheet ja huomautukset koodiston mukaisesta virheestä:

{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "invalid",
"details": {
"coding": [
{
"system": "urn:oid:1.2.246.537.5.40112.2006",
"code": "5A00013",
"display": "Virheellinen pakollinen tieto"
}
]
},
"diagnostics": "documentOid"
}
]
}

Esimerkki virheestä, jossa on mukana myös validointihuomio:

{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "invalid",
"details": {
"coding": [
{
"system": "urn:oid:1.2.246.537.5.40112.2006",
"display": "Virhe sanoman eheydessä.",
"code": "4Y00007"
}
]
},
"diagnostics": "Joissain tapauksissa virheen tarkempi kuvaus."
},
{
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/operationoutcome-issue-line",
"valueInteger": 1
},
{
"url": "http://hl7.org/fhir/StructureDefinition/operationoutcome-issue-col",
"valueInteger": 2576
},
{
"url": "http://hl7.org/fhir/StructureDefinition/operationoutcome-message-id",
"valueString": "Validation_VAL_Profile_Minimum"
}
],
"severity": "error",
"code": "processing",
"details": {
"coding": [
{
"system": "http://hl7.org/fhir/java-core-messageId",
"code": "Validation_VAL_Profile_Minimum"
}
]
},
"diagnostics": "Appointment.identifier.value: minimum required = 1, but only found 0 (from https://pta.kanta.fi/fhir/StructureDefinition/AppointmentAppointment)",
"location": [
"Bundle.entry[0].resource/*Appointment/null*/.identifier[0]",
"Line[1] Col[2576]"
]
}
]
}