Handling Errors

MediBridgeX strictly adheres to the FHIR R4 OperationOutcome specification for data validation errors, and uses RFC 7807 (Problem Details for HTTP APIs) for gateway-level networking faults.

FHIR Validation Errors

When our engine detects malformed FHIR payloads or invalid HL7 mappings, it immediately returns a 400 Bad Request or 422 Unprocessable Entity. The response body will contain an OperationOutcome resource detailing the exact JSON Path expression that failed validation.

Validation Failure Response
1{
2  "resourceType": "OperationOutcome",
3  "issue": [
4    {
5      "severity": "error",
6      "code": "invalid",
7      "details": {
8        "coding": [
9          {
10            "system": "http://hl7.org/fhir/ValueSet/operation-outcome",
11            "code": "MSG_PARAM_INVALID"
12          }
13        ],
14        "text": "Invalid parameter 'birthDate'. Expected format YYYY-MM-DD."
15      },
16      "expression": [
17        "Patient.birthDate"
18      ]
19    }
20  ]
21}

HTTP Status Codes

  • 400
    Bad Request

    Malformed syntax in the request payload or missing required parameters.

  • 401
    Unauthorized

    Invalid, expired, or missing Bearer token in the Authorization header.

  • 403
    Forbidden

    The JWT lacks the required OAuth 2.0 scopes to access this resource.

  • 404
    Not Found

    The requested FHIR resource ID does not exist in the tenant's data silo.