Errors and safe retries

Interpret API errors and avoid duplicate or conflicting scheduling changes.

Read the error response

API errors use statusCode, a stable machine-readable code, and a message. Optional details contain validation messages or contextual fields and choices.

This illustrative response shows the error shape:

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "The request could not be completed"
}

Branch on code where the API documents a specific condition. Do not parse message text or treat all errors with the same HTTP status as equivalent.

Status	Meaning and next step
400	Invalid request. Inspect code and details, then correct the input.
401	Missing, invalid, or expired token, or inactive client. Check authentication.
403	The token or API client lacks a required action scope.
404	The resource does not exist or is outside your dealership access.
409	A scheduling conflict, configuration issue, or appointment-state restriction. Inspect the code before refreshing availability or changing configuration.
422	Unsupported scheduler behavior or missing, conflicting, or unsupported selections/details. Inspect the code and details.
500	An unexpected server failure. Do not assume a mutation had no effect.
502	An upstream failure or an unconfirmed mutation. Distinguish preflight failure from an unknown write outcome.

Handle discovery failures

• Check that the dealership has exactly one scheduling integration configured and that the API supports it.
• Use IDs from discovery for the same vehicle, department, and services. Do not reuse unrelated selections.
• Provide any customer or vehicle details requested by the scheduler. Check service comment requirements before booking.
• If a slot is no longer available, search again and ask the customer to choose a new time.

SCHEDULER_UNAVAILABLE or AMBIGUOUS_SERVICES can occur during preflight discovery before an appointment write is attempted. Inspect the code and context rather than treating every 502 as an unknown booking.

Do not blindly retry writes

Availability is not a reservation. Booking has no durable idempotency guarantee, and repeating a request after a timeout can create a duplicate appointment.

Treat network timeouts and responses indicating an unknown outcome as requiring reconciliation:

Condition	What to do
BOOKING_OUTCOME_UNKNOWN	The booking write could not be confirmed. Reconcile with the dealership or scheduler before submitting another booking.
UPDATE_OUTCOME_UNKNOWN	The update write could not be confirmed. Check the upstream outcome with the dealership or scheduler before another update.
REPLACEMENT_PARTIAL_FAILURE	The original appointment was canceled and its replacement was not confirmed. Request operator review.
Cancellation outcome unknown	Confirm the cancellation with the dealership or scheduler before retrying.

Reading or searching Spark appointments can provide local context, but those snapshots are not proof of the current upstream state. A missing local booking does not prove that booking failed.

Ask for help

Contact [e-mail] with:

• The HTTP method, endpoint, and approximate request time.
• The dealership and appointment IDs, when available.
• The response status and error code, plus relevant sanitized details.
• Whether the request timed out and whether any retry has already occurred.

Do not include client secrets, access tokens, or unnecessary customer information.