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

# Missing dealer listings

> Symptom → cause → corrected request → verification for every common way dealer (Encar) listings go missing from a storefront, with the exact error bodies the API returns.

Each entry below starts from what you see, names the documented cause, gives a corrected request, and tells you what to inspect to confirm the fix. **Verification always means reading the response — status code, `error.code`, headers and `source_status` — not whether cards appeared.** Auction cards rendering says nothing about the dealer request.

Contracts referenced: [Dealer source constraints](/endpoints/vehicles#dealer-source-constraints), [Mixed source](/endpoints/vehicles#mixed-source-first-page-only), [Dealer upstream unavailability](/endpoints/vehicles#dealer-upstream-unavailability), [Errors](/errors). The storefront recipe these fixes assume is [Combined inventory storefront](/combined-inventory-storefront).

<Note>
  Using an AI coding assistant? Connect it to the [documentation connector](/ai-builders) and paste the error body — it can match it to the entries below. Paste the status, `error.code`, `error.message` and `request_id`; never your API key.
</Note>

<a id="t1" />

## T1 — `source=dealer requires make`

**Symptom.** `400` with:

```json theme={null}
{ "error": { "code": "validation_error", "message": "source=dealer requires make",
             "request_id": "req_…", "details": { "field": "make" } } }
```

**Cause.** The dealer upstream resolves inventory per manufacturer, so a dealer request without `make` cannot be executed. This happens when the storefront sends the dealer request before the user has chosen a make, or when the auction query (where `make` is optional) is forwarded to the dealer request unchanged.

**Corrected request.**

```bash theme={null}
curl -H "x-api-key: $LMN_API_KEY" \
  "https://sandbox-api.lmnauto.com/v1/vehicles?source=dealer&make=BMW&limit=24"
```

Until a make is selected, do not issue the dealer request at all; show "Select a make to include dealer listings" ([storefront guide](/combined-inventory-storefront#step-2-three-request-shapes)). `make` may be a CSV (`make=Hyundai,Kia`).

**Verify.** `200`; `source_status` present; rows have `source: "dealer"` and `encar_…` IDs.

<a id="t2" />

## T2 — `auction_status cannot be combined with source=dealer`

**Symptom.** `400` with:

```json theme={null}
{ "error": { "code": "validation_error", "message": "auction_status cannot be combined with source=dealer",
             "request_id": "req_…", "details": { "field": "auction_status" } } }
```

The same shape, with a different `details.field`, appears for `auction_date_from` / `auction_date_to`, `accident_grade`, `exterior_grade`, `auction_count_min` / `auction_count_max`, and `orderable_only=true`.

**Cause.** Dealer listings have no auction, so auction-only filters are rejected rather than silently ignored. The storefront forwarded its auction filters to the dealer request.

**Corrected request.** Build the dealer request from the common-filter whitelist only ([which filters go where](/combined-inventory-storefront#which-filters-go-to-which-request)):

```bash theme={null}
# auction request keeps auction_status
curl -H "x-api-key: $LMN_API_KEY" \
  "https://sandbox-api.lmnauto.com/v1/vehicles?source=glovis,sk,aj,lotte,kcar&make=BMW&auction_status=upcoming&limit=24"
# dealer request drops it
curl -H "x-api-key: $LMN_API_KEY" \
  "https://sandbox-api.lmnauto.com/v1/vehicles?source=dealer&make=BMW&limit=24"
```

**Verify.** Both requests return `200`. The dealer response has no `auction_result` values (they are `null` for dealer rows).

<a id="t3" />

## T3 — "All sources" shows only auctions

**Symptom.** No error. The page labelled "All sources" shows auction cards only; the dealer request either never ran or returned nothing you can see.

**Causes** — check in this order:

1. **`source` was omitted.** Omitting `source` searches auction listings only, even when `make` is present. A present `X-LMN-Filtered-Out: dealer=N` header on such a request is a best-effort estimate of dealer cars an auction-only filter would have hidden — the dealer upstream is queried to compute that count, but no dealer rows are returned ([Null-strict semantics](/endpoints/vehicles#null-strict-semantics)).
2. **No `make` yet,** so your backend (correctly) skipped the dealer request — but the UI did not say so.
3. **`orderable_only=true`** was sent. It returns only `upcoming` auction cars with an open order window; dealer rows are excluded by definition.
4. **Dealer degraded.** A mixed first-page request returned `200` with `X-LMN-Partial-Dealer-Unavailable: 1` and `X-LMN-Dealer-Unavailable-Sources: encar`, and the page rendered the auction rows without noticing (see T6).
5. **A "Buy now" toggle is gating the dealer request.** Dealer cars are Buy now, but they belong in "All sources" whether or not that toggle is on ([source vs. purchase method](/combined-inventory-storefront#source-vs-purchase-method)).

**Corrected request.** Two explicit requests:

```bash theme={null}
curl -H "x-api-key: $LMN_API_KEY" \
  "https://sandbox-api.lmnauto.com/v1/vehicles?source=glovis,sk,aj,lotte,kcar&make=BMW&limit=24"
curl -H "x-api-key: $LMN_API_KEY" \
  "https://sandbox-api.lmnauto.com/v1/vehicles?source=dealer&make=BMW&limit=24"
```

**Verify.** In your backend logs, both requests were sent. The dealer response is `200` with `source_status.encar.status` of `fresh` or `stale` and rows with `source: "dealer"`. If it is `200` with zero rows and a healthy `source_status`, the integration works and the filter is just narrow — broaden it (drop `model`, widen year/price, try Hyundai or Kia).

<a id="t4" />

## T4 — First page works, the next page fails

**Symptom.** Page 1 renders. Loading more returns `400`:

```json theme={null}
{ "error": { "code": "mixed_source_pagination_unsupported",
             "message": "Paginating combined auction+dealer results is not supported. Query each source separately when using cursor.",
             "request_id": "req_…", "details": { "field": "cursor" } } }
```

**Cause.** The first page was a single mixed request (`source=glovis,dealer`), which is supported, and the next page sent that mixed `source` together with `cursor`, which is not ([Mixed source — first page only](/endpoints/vehicles#mixed-source-first-page-only)).

**Corrected request.** Paginate each source with its own cursor, from page 1:

```bash theme={null}
# auction page 2
curl -H "x-api-key: $LMN_API_KEY" \
  "https://sandbox-api.lmnauto.com/v1/vehicles?source=glovis,sk,aj,lotte,kcar&make=BMW&limit=24&cursor=<auction next_cursor>"
# dealer page 2
curl -H "x-api-key: $LMN_API_KEY" \
  "https://sandbox-api.lmnauto.com/v1/vehicles?source=dealer&make=BMW&limit=24&cursor=<dealer next_cursor>"
```

**Verify.** Each page-2 request returns `200` and its rows differ from page 1 of the same source. `next_cursor: null` marks the end of that source. If you request `limit` above 48 on dealer, the response carries `X-LMN-Dealer-Page-Max: 48` — keep following the dealer cursor.

<a id="t5" />

## T5 — Changing a filter reuses the old cursor

**Symptom.** After changing `model`, sort or any filter, the list looks wrong: the first cars are missing, results seem to start mid-way, or the page is unexpectedly empty. There is usually **no error** — `/v1/vehicles` does not return `invalid_cursor`; the only error case is `400 validation_error` with `details.field: "cursor"` after a taxonomy version change ([Model vs. sub-model → Pagination](/endpoints/vehicles#model-vs-sub-model)).

**Cause.** A cursor is a position in one specific result set. On `/v1/vehicles`, sending it with different filters or a different `sort` does not fail — it returns page *N* of the *new* result set, silently skipping its first page (observed: a page-2 cursor reused with `sort=price_asc` returned `200` with page 2 of the price-sorted set). [Conventions → Pagination](/conventions#pagination).

**Corrected behaviour.** On any filter or sort change, discard **both** cursors and request page 1 of each source:

```bash theme={null}
curl -H "x-api-key: $LMN_API_KEY" \
  "https://sandbox-api.lmnauto.com/v1/vehicles?source=dealer&make=BMW&model=X5&limit=24"   # no cursor
```

**Verify.** In your network tab, the requests that follow a filter change carry no `cursor` parameter, and the first row of the new result is a page-1 row.

<a id="t6" />

## T6 — Dealer source unavailable, stale or partial

**Symptom.** One of:

* Dealer-only request: `503`

  ```json theme={null}
  { "error": { "code": "dealer_upstream_unavailable",
               "message": "Dealer inventory upstream is currently unavailable", "request_id": "req_…" } }
  ```

* Mixed first-page request: `200` with auction rows only, headers `X-LMN-Partial-Dealer-Unavailable: 1` and `X-LMN-Dealer-Unavailable-Sources: encar`, and body `source_status.encar.status: "unavailable"`.

* Dealer request: `200` with `source_status.encar.status: "stale"` (cached rows up to 30 minutes old, `as_of` set) or `"partial"` (some makes of a multi-make query answered).

**Cause.** The dealer side is a live proxy to a third-party retail site. `503` means every requested dealer source failed and no eligible cache existed; `stale` means LMN served its last good page; `partial` means some branches answered. None of these are integration bugs. [Dealer upstream unavailability](/endpoints/vehicles#dealer-upstream-unavailability), [`dealer_upstream_unavailable`](/errors#per-code-troubleshooting).

**Corrected behaviour.** Keep the auction rows, show a "dealer listings temporarily unavailable" notice (with `as_of` when `stale`), and retry **only the dealer request** after 5–30 seconds. Preserve the previous dealer rows rather than blanking the section.

**Verify.** The retry returns `200` with `source_status.encar.status: "fresh"`. If a dealer request stays `503` for more than about two minutes, send the `request_id` to support ([escalation template](/ai-builders#if-something-doesnt-work)) — auction requests are unaffected meanwhile.

<a id="t7" />

## T7 — An API failure is shown as "No vehicles found"

**Symptom.** The page says no vehicles match, but the backend actually received a non-2xx response — most often `401`:

```json theme={null}
{ "error": { "code": "invalid_api_key", "message": "Invalid or revoked API key", "request_id": "req_…" } }
```

or a `400` from T1/T2, a `429` ([trial budget exhausted](/errors#trial-budget-exhausted)), or a `503` (T6) — or the fetch threw before any response.

**Cause.** The storefront treats "no rows" and "the request failed" as the same state, usually because an error path returns `[]`.

**Corrected behaviour.** Separate the states ([Failures vs. empty results](/combined-inventory-storefront#failures-vs-empty-results)): on non-2xx or a thrown fetch, render the HTTP status, `error.code`, `error.message` and `request_id`; reserve "No cars match these filters" for `200` with `data: []`.

**Verify.** Temporarily use a wrong key: the page must show `401 invalid_api_key` with a `request_id`. Restore the key and confirm a narrow filter shows the empty state instead. Keep the two visually distinct.

<a id="t8" />

## T8 — `options_include` rejected for dealer

**Symptom.** `400` with:

```json theme={null}
{ "error": { "code": "validation_error",
             "message": "options_include value not available for source=dealer: dashcam",
             "request_id": "req_…", "details": { "field": "options_include", "option": "dashcam" } } }
```

**Cause.** `panoramic_sunroof` and `dashcam` have no dealer-side filter and are rejected rather than silently dropped. Every other documented token works on dealer. The same forwarding mistake as T2 ([`options_include` for dealer](/endpoints/vehicles#options_include-for-dealer-full-catalog)).

**Corrected request.** Drop the two tokens from the dealer request (keep them on the auction one):

```bash theme={null}
curl -H "x-api-key: $LMN_API_KEY" \
  "https://sandbox-api.lmnauto.com/v1/vehicles?source=dealer&make=BMW&options_include=sunroof,ventilated_seats&limit=24"
```

**Verify.** `200`; rows carry both options in `options`.

## Still stuck?

Collect the exact request (sanitized query), the HTTP status, the full error body and the `request_id`, and the backend function that built the request, and send them to `partners@lmnauto.com` using the [escalation template](/ai-builders#if-something-doesnt-work). **Never include your API key.**


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