> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sparkserv.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```json theme={null}
{
  "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](https://docs.sparkserv.com/authentication.md). |
| `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 [support@sparkserv.com](mailto:support@sparkserv.com) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.