Skip to main content

​
Error Responses

The FHIR API follows the FHIR specification for error handling, returning OperationOutcome resources for errors.

​
HTTP Status Codes

The server uses standard HTTP status codes:
  • 200 OK - Successful operation
  • 201 Created - Resource created successfully
  • 204 No Content - Successful deletion or HEAD request
  • 400 Bad Request - Invalid request (malformed syntax, validation errors)
  • 401 Unauthorized - Authentication required
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found
  • 405 Method Not Allowed - HTTP method not supported for endpoint
  • 409 Conflict - Version conflict (e.g., during update)
  • 410 Gone - Resource was deleted
  • 412 Precondition Failed - Conditional operation failed
  • 422 Unprocessable Entity - Business rule violation
  • 500 Internal Server Error - Server error

​
OperationOutcome Format

Errors are returned as OperationOutcome resources: 
{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "details": {
        "text": "Resource validation failed"
      },
      "diagnostics": "Patient.name[0].family: minimum required = 1, but only found 0"
    }
  ]
}

​
Common Error Scenarios

​
Validation Errors (400)

When a resource fails validation: 
{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "details": {
        "text": "Required field missing: Patient.name"
      }
    }
  ]
}

​
Not Found (404)

When a resource doesn’t exist: 
{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "not-found",
      "details": {
        "text": "Resource Patient/123 not found"
      }
    }
  ]
}

​
Version Conflict (409)

When updating a resource with an outdated version: 
{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "conflict",
      "details": {
        "text": "Version conflict: current version is 2, provided version is 1"
      }
    }
  ]
}