Appointment API — Endpoints, Errors and Warnings Reference
This document lists each Appointment API endpoint and the error codes and warning codes that may be returned in API responses. Use it to handle errors and warnings in your integration.
Base URL: https://api.mykaarma.com/appointment/v2
1. Create appointment
POST /dealer/{dealerUuid}/appointment
Errors
| Error code | Description |
|---|---|
SCHEDULER_FEATURE_NOT_ENABLED | Appointment Scheduling feature is not enabled for this dealership. |
INVALID_DEALER_UUID | The dealer identifier (UUID) provided in the request does not match any known dealer. |
INCORRECT_DEALER_INFO | No dealer found for the given dealer UUID. |
DUPLICATE_APPOINTMENT_FOUND | An appointment already exists for this customer and vehicle combination. Cancel or update the existing appointment instead. |
APPOINTMENT_KEY_EXISTS | The provided appointment key is already used by another appointment. |
MISSING_CUSTOMER_UUID | Customer UUID was not provided in the request body. |
INCORRECT_USER_INFO | No user found for the given user/advisor UUID. |
USER_UUID_MANDATORY | Advisor (userUuid) is required by dealer preferences but was not provided. |
NO_SA_AVAILABLE | No service advisor is available for the requested day. Try a different date or time slot. |
SLOT_UNAVAILABLE | The requested time slot is not available for appointment scheduling. |
NO_TIME_INTERVAL_EXISTS | No valid slot exists for the given time. |
APPOINTMENT_VIOLATES_CAPACITY_PLANNING_CONSTRAINTS | The appointment cannot be created because it would exceed the dealership's configured capacity limits for the requested time. |
TRANSPORT_OPTION_MISMATCH | The fields altTransportOption and transportOption do not refer to the same option. |
TRANSPORT_OPTION_UNAVAILABLE | The requested transport option is not available for the selected time. |
TRANSPORT_OPTION_INVALID | The requested transport option does not exist. |
CUSTOMER_INFO_MISSING | Minimum required customer info (e.g. name and phone/email or VIN) was not provided. |
START_DATE_BEFORE_END_DATE | The appointment start date is after the end date. Ensure start date/time is earlier than end date/time. |
INVALID_APPT_START_DATE_TIME | Invalid start time; use format yyyy-MM-dd'T'HH:mm:ss (e.g., 2026-03-15T09:30:00). |
INVALID_APPT_END_DATE_TIME | Invalid end time; use format yyyy-MM-dd'T'HH:mm:ss (e.g., 2026-03-15T09:30:00). |
APPT_START_END_DATE_MISMATCH | Start date and end date differ; the date part of start and end must match. |
VEHICLE_NOT_FOUND | Vehicle not found for the customer with the provided VIN or vehicle key. |
VEHICLE_UUID_NOT_FOUND | Vehicle not found for the customer with the provided vehicle UUID. |
NO_DATE | Date was not provided. |
PAST_DATE | A past date was provided. |
INVALID_DATE_FORMAT | The date provided is not in the expected format. Use yyyy-MM-dd (e.g., 2026-03-15). |
INTERNAL_ERROR | An unexpected error occurred on the server. |
INTERNAL_SERVER_ERROR | An unexpected server error occurred. |
Warnings
| Warning code | Description |
|---|---|
MAX_APPOINTMENTS_EXCEEDED_FOR_CUSTOMER | The customer has reached the maximum number of allowed future appointments. No additional appointments can be scheduled until an existing appointment is completed or canceled. |
Appointment-rule warnings (APPT_RULE_WARN_*) | May appear when the requested slot or selection violates scheduling rules; see Appointment-rule warning codes below. |
2. Update appointment / Cancel appointment
PATCH /department/{dealerDepartmentUuid}/appointment/{appointmentUuid}
Errors
All errors listed for Create appointment, plus:
| Error code | Description |
|---|---|
INVALID_SAR_UUID | The appointment identifier (UUID) provided in the request does not match any existing appointment. |
INCORRECT_APPOINTMENT | No appointment found for the given appointment UUID. |
INCORRECT_APPOINTMENT_STATUS | The appointment status provided is incorrect. |
INCORRECT_APPOINTMENT_DEPARTMENT | No appointment found for the given combination of appointment and department. |
EMPTY_SAR_UUID | The appointment identifier (UUID) was passed as empty. This field is required when updating or fetching an appointment. |
NO_SAR_UUID | Appointment UUID was not provided. |
UPDATE_APPOINTMENT_FAILED_TO_ACQUIRE_LOCK | Another update is already in progress for this appointment. Wait a moment and retry the request. |
APPOINTMENT_CANNOT_BE_UPDATED_RO_MAPPED | The appointment is linked to a repair order and cannot be updated. |
NO_SAR_FOUND | No appointment was found for the given appointment identifier (UUID). |
Warnings
| Warning code | Description |
|---|---|
MAX_APPOINTMENTS_EXCEEDED_FOR_CUSTOMER | The customer has reached the maximum number of allowed future appointments. No additional appointments can be scheduled until an existing appointment is completed or canceled. |
Appointment-rule warnings (APPT_RULE_WARN_*) | May appear when the requested slot or selection violates scheduling rules; see Appointment-rule warning codes below. |
3. Create draft appointment
POST /dealer/{dealerUuid}/draftAppointment
Errors
| Error code | Description |
|---|---|
INVALID_DEALER_UUID | The dealer identifier (UUID) provided in the request does not match any known dealer. |
SCHEDULER_FEATURE_NOT_ENABLED | Appointment Scheduling feature is not enabled for this dealership. |
APPOINTMENT_SAVE_FAILED | The system was unable to save the draft appointment. This is typically a transient server-side issue — retry the request. |
APPOINTMENT_DOES_NOT_EXIST | No draft appointment exists for the given customer and appointment identifier. |
APPOINTMENT_FETCH_FAILED | The system was unable to retrieve the draft appointment. This is typically a transient server-side issue — retry the request. |
DEEPLINK_CREATION_FAILED | Failed to create the consumer scheduler link. |
INTERNAL_ERROR | An unexpected error occurred on the server. |
INTERNAL_SERVER_ERROR | An unexpected server error occurred. |
4. Get appointment by UUID
GET /dealerDepartment/{departmentUuid}/uuid/{appointmentUuid}
Errors
| Error code | Description |
|---|---|
INVALID_DEPT_UUID | The department identifier (UUID) provided in the request does not match any known department for this dealer. |
INVALID_SAR_UUID | The appointment identifier (UUID) provided in the request does not match any existing appointment. |
INCORRECT_APPOINTMENT | No appointment found for the given appointment UUID. |
EMPTY_SAR_UUID | The appointment identifier (UUID) was passed as empty. This field is required when updating or fetching an appointment. |
NO_SAR_FOUND | No appointment was found for the given appointment identifier (UUID). |
INTERNAL_ERROR | An unexpected error occurred on the server. |
INTERNAL_SERVER_ERROR | An unexpected server error occurred. |
5. Get appointments by appointment date
GET /dealerDepartment/{departmentUuid}/date/{date}
Errors
| Error code | Description |
|---|---|
INVALID_DEPT_UUID | The department identifier (UUID) provided in the request does not match any known department for this dealer. |
INVALID_DATE_FORMAT | The date provided is not in the expected format. Use yyyy-MM-dd (e.g., 2026-03-15). |
NO_DATE | Date was not provided. |
DATE_EMPTY | A required date field was not provided in the request. |
INTERNAL_ERROR | An unexpected error occurred on the server. |
INTERNAL_SERVER_ERROR | An unexpected server error occurred. |
6. Get appointments by order UUID
GET /dealerDepartment/{departmentUuid}/order/{orderUuid}
Errors
| Error code | Description |
|---|---|
INVALID_DEPT_UUID | The department identifier (UUID) provided in the request does not match any known department for this dealer. |
INVALID_ORDER_UUID | The order UUID provided in the request is invalid or no order was found. |
INTERNAL_ERROR | An unexpected error occurred on the server. |
INTERNAL_SERVER_ERROR | An unexpected server error occurred. |
7. Get appointments for customer
GET /dealerDepartment/{departmentUuid}/customer/{customerUuid}
Errors
| Error code | Description |
|---|---|
INVALID_DEPT_UUID | The department identifier (UUID) provided in the request does not match any known department for this dealer. |
MISSING_CUSTOMER_UUID | Customer UUID was not provided in the request. |
MISSING_DEALER_DEPARTMENT_UUID | Department UUID was not provided in the request. |
INVALID_CUSTOMER_UUID | The customer UUID provided in the request is invalid or no customer was found. |
INTERNAL_ERROR | An unexpected error occurred on the server. |
INTERNAL_SERVER_ERROR | An unexpected server error occurred. |
8. Get appointments by filter (list)
POST /department/{dealerDepartmentUUID}/list
Errors
| Error code | Description |
|---|---|
INVALID_DEPT_UUID | The department identifier (UUID) provided in the request does not match any known department for this dealer. |
INVALID_DEALER_UUID | The department UUID could not be resolved to a dealer (invalid or unknown department). |
MISSING_OR_INVALID_PAGE_NUMBER | Page number is missing or invalid. |
MISSING_OR_INVALID_PAGE_SIZE | Page size is missing or invalid. |
INVALID_START_DATE | The startDate must be in a valid date format yyyy-MM-dd when provided. |
INVALID_END_DATE | The endDate must be in a valid date format yyyy-MM-dd when provided. |
INVALID_START_CREATED_DATE | The startCreatedDate must be in a valid date format yyyy-MM-dd when provided. |
INVALID_END_CREATED_DATE | The endCreatedDate must be in a valid date format yyyy-MM-dd when provided. |
INVALID_CREATED_BY | The createdBy (appointment source) value is invalid. |
INVALID_ORDER_BY | The orderBy value is invalid. |
INVALID_REQUEST | At least one filter parameter must be provided (e.g. appointmentKeys, customerUuids, startDate, endDate, startCreatedDate, or endCreatedDate). |
INTERNAL_ERROR | An unexpected error occurred on the server. |
INTERNAL_SERVER_ERROR | An unexpected server error occurred. |
9. Save opcode
POST /department/{dealerDepartmentUuid}/opcode
Errors
| Error code | Description |
|---|---|
INVALID_DEPT_UUID | The department identifier (UUID) provided in the request does not match any known department for this dealer. |
OPCODE_ALREADY_EXISTS | An opcode with the given code already exists; use PUT to update. |
INCORRECT_OPCODE | No opcode found for the given opcode UUID. |
OPCODE_LABORCODE_MANDATORY | LaborOpCode is a required field. |
KOPCODE_SAVE_OPERATIONS_FAILURE | Failed to save operations. |
INTERNAL_ERROR | An unexpected error occurred on the server. |
INTERNAL_SERVER_ERROR | An unexpected server error occurred. |
10. Get eligible advisors
GET /dealer/{dealerUuid}/eligibleAdvisor/list
Errors
| Error code | Description |
|---|---|
INVALID_DEALER_UUID | The dealer identifier (UUID) provided in the request does not match any known dealer. |
SCHEDULER_FEATURE_NOT_ENABLED | Appointment Scheduling feature is not enabled for this dealership. |
INTERNAL_ERROR | An unexpected error occurred on the server. |
INTERNAL_SERVER_ERROR | An unexpected server error occurred. |
11. Get transport options for dealer/department
GET /department/{dealerDepartmentUUID}/transportOption/list
Errors
| Error code | Description |
|---|---|
INVALID_DEPT_UUID | The department identifier (UUID) provided in the request does not match any known department for this dealer. |
INTERNAL_ERROR | An unexpected error occurred on the server. |
INTERNAL_SERVER_ERROR | An unexpected server error occurred. |
12. Get resource availability
POST /department/{dealerDepartmentUUID}/availability
Errors
| Error code | Description |
|---|---|
INVALID_DEPT_UUID | The department identifier (UUID) provided in the request does not match any known department for this dealer. |
SELECTED_ENTITIES_NOT_FOUND | None of the selected entities (service advisor, transport option, or team) were found for this dealership. |
SELECTED_DEALER_ASSOCIATES_NOT_FOUND | None of the selected dealer associates were found. |
SELECTED_TRANSPORT_OPTIONS_NOT_FOUND | None of the transport options specified in the request were found for this dealership. |
INTERNAL_ERROR | An unexpected error occurred on the server. |
INTERNAL_SERVER_ERROR | An unexpected server error occurred. |
Warnings
| Warning code | Description |
|---|---|
NUMBER_OF_DAYS_EXCEEDS_MAX_LIMIT | The request is fetching availability for more than 21 days. Support for fetching availability beyond 21 days will be removed in a future release. |
PAST_DATES_AVAILABILITY_BEING_FETCHED | Availability is being requested for dates in the past. Note that past time slots will be automatically marked as unavailable. |
Appointment-rule warnings (APPT_RULE_WARN_*) | May appear in unavailabilityWarningList or warnings[]; see Appointment-rule warning codes below. |
13. Get first available slot
POST /department/{dealerDepartmentUUID}/first-available-slot
Errors
| Error code | Description |
|---|---|
INVALID_DEPT_UUID | The department identifier (UUID) provided in the request does not match any known department for this dealer. |
SELECTED_ENTITIES_NOT_FOUND | None of the selected entities (service advisor, transport option, or team) were found for this dealership. |
SELECTED_DEALER_ASSOCIATES_NOT_FOUND | None of the selected dealer associates were found. |
SELECTED_TRANSPORT_OPTIONS_NOT_FOUND | None of the transport options specified in the request were found for this dealership. |
INTERNAL_ERROR | An unexpected error occurred on the server. |
INTERNAL_SERVER_ERROR | An unexpected server error occurred. |
Warnings
| Warning code | Description |
|---|---|
NUMBER_OF_DAYS_EXCEEDS_MAX_LIMIT | The request is fetching availability for more than 21 days. Support for fetching availability beyond 21 days will be removed in a future release. |
PAST_DATES_AVAILABILITY_BEING_FETCHED | Availability is being requested for dates in the past. Note that past time slots will be automatically marked as unavailable. |
Appointment-rule warnings (APPT_RULE_WARN_*) | May appear in unavailabilityWarningList or warnings[]; see Appointment-rule warning codes below. |
14. Get BrandYear for dealer
POST /dealer-vehicle-config/brand-years
Errors
| Error code | Description |
|---|---|
INVALID_DEALER_UUID | The dealer identifier (UUID) provided in the request does not match any known dealer. |
DEALER_UUID_MISSING | Dealer UUID was not provided (request body dealer UUID list is empty or missing). |
INTERNAL_ERROR | An unexpected error occurred on the server. |
INTERNAL_SERVER_ERROR | An unexpected server error occurred. |
15. Get vacant time slot info with rules (deprecated)
POST /department/{dealerDepartmentUUID}/vacantTimeSlotInfoWithRules
Deprecation
This endpoint is deprecated. Use Get resource availability (POST /department/{dealerDepartmentUUID}/availability) instead.
Errors
Same as Get resource availability (department validation, selected entities, internal errors).
Warnings
| Warning code | Description |
|---|---|
NUMBER_OF_DAYS_EXCEEDS_MAX_LIMIT | The request is fetching availability for more than 21 days. Support for fetching availability beyond 21 days will be removed in a future release. |
PAST_DATES_AVAILABILITY_BEING_FETCHED | Availability is being requested for dates in the past. Note that past time slots will be automatically marked as unavailable. |
Appointment-rule warnings (APPT_RULE_WARN_*) | May appear in slot-level warningList or warningCodes; see Appointment-rule warning codes below. |
Appointment-rule warning codes
These warning codes may be returned in create appointment, update appointment, get resource availability, get first available slot, and get vacant time slot info with rules responses (for example in warnings[], unavailabilityWarningList, or slot-level warning lists). They indicate that the requested time slot or selection violates a scheduling rule configured at the dealership. The warningDescription in the response may contain actual values (e.g., advisor name, specific date) in place of placeholders.
| Warning code | Description |
|---|---|
APPT_RULE_WARN_DEALER_PER_DAY | Dealer has reached the maximum appointment limit for that day of the week. |
APPT_RULE_WARN_DEALER_PER_DATE | Dealer has reached the maximum appointment limit for that specific date. |
APPT_RULE_WARN_DEALER_PER_DAY_PER_SLOT | Dealer has reached the per-slot limit for that day of the week. |
APPT_RULE_WARN_DEALER_PER_DATE_PER_SLOT | Dealer has reached the per-slot limit for that specific date. |
APPT_RULE_WARN_DEALER_PER_SLOT_APPT_COUNT | The selected time slot is marked unavailable in the dealer schedule for that day. |
APPT_RULE_WARN_DEALER_HOURS_OPERATION | The selected time slot is outside the dealer’s hours of operation. |
APPT_RULE_WARN_DEALER_HOURS_NON_OPERATION | The selected time slot is marked unavailable for that date (e.g. holiday or closure). |
APPT_RULE_WARN_DEALER_OFFSET | The selected time slot is too close to the current time (minimum lead time not met). |
APPT_RULE_WARN_SA_PER_DAY_OF_WEEK | The selected advisor has reached their maximum appointments for that day of the week. |
APPT_RULE_WARN_SA_PER_DATE | The selected advisor has reached their maximum appointments for that date. |
APPT_RULE_WARN_SA_PER_DAY_PER_SLOT | The selected advisor has reached their per-slot limit for that day of the week. |
APPT_RULE_WARN_SA_PER_DATE_PER_SLOT | The selected advisor has reached their per-slot limit for that date. |
APPT_RULE_WARN_SA_WEEKLY_SLOT_OFF | The selected time slot is blocked on the advisor’s weekly schedule. |
APPT_RULE_WARN_SA_DATEWISE_SLOT_OFF | The selected time slot is blocked on the advisor’s schedule for that date. |
APPT_RULE_WARN_SA_RECURRENCE_DATE | The selected date is before the advisor’s recurring schedule start date. |
APPT_RULE_WARN_NO_TRANSPORT_OPTION | No transport option is available for the selected time slot. |
APPT_RULE_WARN_TRANSPORT_OPTION_PER_SLOT | The requested transport option is not available for the selected time slot. |
APPT_RULE_WARN_SUM_INDIVIDUAL_PER_DATE | Combined appointment limit across advisors has been reached for that date. |
APPT_RULE_WARN_SUM_INDIVIDUAL_PER_SLOT | Combined per-slot limit across advisors has been reached for that date and slot. |
APPT_RULE_WARN_INVALID_DA_TO_TEAM_COMBINATION | The combination of advisor, transport option, or team is invalid or unavailable. |
APPT_RULE_WARN_CAMPAIGNS_LEAD_TIME | The slot is unavailable due to recall campaign lead time. |
APPT_RULE_WARN_CAMPAIGNS_DAILY_LIMIT_EXCEEDED | Daily limit for the recall campaign has been reached for that date. |
APPT_RULE_WARN_OPCODES_LEAD_TIME | The slot is unavailable due to opcode lead time. |
APPT_RULE_WARN_OPCODES_DAILY_LIMIT_EXCEEDED | Daily limit for the opcode has been exceeded. |
APPT_RULE_WARN_CAPACITY_PLANNING_CONSTRAINT_VIOLATED | The slot would violate a capacity planning constraint. |
General / shared errors
These may be returned by any endpoint (for example for authentication or authorization):
| Error code | Description |
|---|---|
INVALID_AUTHORITY_KEY_IN_REQUEST | The authority key (API credential) in the request is invalid. |
UNAUTHORIZED | The request could not be authenticated with the provided credentials. |
NO_AUTHENTICATION_PROVIDED | No authentication was provided in the request. |
FORBIDDEN | The request was authenticated but you are not Authorized to perform this action. |
INTERNAL_ERROR | An unexpected error occurred on the server. |
INTERNAL_SERVER_ERROR | An unexpected server error occurred. |