Error Handling

HTTP status codes

Code	Meaning	Action
`200`	Success	All or some appointments processed successfully. Check `warnings` for partial failures.
`400`	Bad Request	Check the `errors` array for field-level validation details.
`401`	Unauthorized	API key is missing, invalid, or the signature does not match. Verify your API key and signing key.
`403`	Forbidden	API key is valid but not authorized for the EHR in the URL path.
`500`	Internal Server Error	Unexpected error on our side. Safe to retry. Contact Insight Health if persistent.

Response examples

Authentication error (401)


{
  "error": "Missing X-API-Key header",
  "success": false
}


{
  "error": "Invalid X-Webhook-Signature header. Ensure the request body is signed with the correct signing key using HMAC-SHA256.",
  "success": false
}

EHR mismatch (403)


{
  "message": "API key is not authorized for EHR 'medicat'. This key is registered for 'nexus'.",
  "success": false,
  "code": 403
}

Validation error (400)

When none of the appointments pass validation, you get a 400 with an errors array listing every field-level issue. Each error is prefixed with the appointment index.


{
  "message": "Validation failed. None of the provided appointments could be processed.",
  "errors": [
    "appointments[0].appointment.id is required.",
    "appointments[0].appointment.status is required.",
    "appointments[0].appointment.start_time is required.",
    "appointments[0].patient.birth_date is required. Format: MM/DD/YYYY.",
    "appointments[1]: 'patient' object is required."
  ],
  "success": false,
  "code": 400
}

Partial success (200 with warnings)

When some appointments sync but others fail validation, you get a 200 with a warnings array for the failures.


{
  "message": "1 appointment(s) synced successfully. 2 validation error(s) on other appointments.",
  "success": true,
  "code": 200,
  "warnings": [
    "appointments[1].appointment.id is required.",
    "appointments[1].patient.id is required."
  ]
}

Full success (200)


{
  "message": "2 appointment(s) synced successfully.",
  "success": true,
  "code": 200
}

Required fields validation

The following fields are validated on each appointment. If any required field is missing, that appointment is rejected with a descriptive error.

Property	Type	Description
`appointment`*	`object`	The appointment object itself must be present.
`id`*	`string`	appointment.id is required.
`status`*	`string`	appointment.status is required.
`start_time`*	`string`	appointment.start_time is required.
`start_date`*	`string`	appointment.start_date is required. Format: MM/DD/YYYY.
`type`*	`string`	appointment.type is required.
`created_time`*	`string`	appointment.created_time is required.
`patient`*	`object`	The patient object itself must be present.
`id`*	`string`	patient.id is required.
`first_name`*	`string`	patient.first_name is required (or provide 'name').
`last_name`*	`string`	patient.last_name is required (or provide 'name').
`birth_date`*	`string`	patient.birth_date is required. Format: MM/DD/YYYY.
`gender`*	`string`	patient.gender is required.
`practitioner`*	`object`	The practitioner object itself must be present.
`id`*	`string`	practitioner.id is required.
`first_name`*	`string`	practitioner.first_name is required (or provide 'name').
`last_name`*	`string`	practitioner.last_name is required (or provide 'name').

* Required field

Retry guidance

Scenario	Action
`401` / `403`	Do not retry. Fix credentials or configuration.
`400`	Do not retry. Fix the request payload using the `errors` array.
`500`	Retry with exponential backoff (1s, 2s, 4s, up to 60s max).
Network timeout	Retry up to 3 times with backoff.