Error Contract

Standard envelope

Most failures use this shape:

{
  "error": "string",
  "status": 400,
  "details": {
    "field": "string",
    "message": "string"
  }
}

details can vary by error type:

• ErrorMessageFieldDetails

{
  "field": "ClinicCode",
  "message": "Clinic Code is required for this call"
}

• ErrorMessageDetails

{
  "message": "There has been an exception encountered while trying to cancel the Order."
}

• Validation list (ErrorResponseBadRequestValidation)

{
  "error": "Validation failed",
  "status": 400,
  "details": [
    { "field": "FieldA", "message": "Message A" },
    { "field": "FieldB", "message": "Message B" }
  ]
}

HTTP status behavior

• 400: bad request or business-rule rejection

• 401: authentication failed (login)

• 403: forbidden (example: patient lockout conditions)

• 404: resource not found in clinic scope

• 500: server error

Integration recommendations

• Parse and log both error and details.message.

• Use details.field to map UI feedback.

• Treat 500 responses as retryable only when your workflow permits.