Errors

Error envelope, full code matrix, and per-code troubleshooting.

​

Error response shape

All non-2xx responses share this envelope:

{
  "error": {
    "code": "past_order_cutoff",
    "message": "The order window for this auction closed at 2026-04-20T12:00:00+09:00.",
    "request_id": "req_8829374",
    "details": {
      "cutoff_at": "2026-04-20T12:00:00+09:00",
      "now": "2026-04-20T12:30:00+09:00"
    }
  }
}

Branch on error.code only. error.message is human-readable English and may evolve. details is structured supplementary info — fields vary per code.

request_id is also returned as the X-Request-Id response header. Include it in any support request.

​

HTTP → code matrix

HTTP	error.code values
400	validation_error, missing_idempotency_key, missing_max_bid, invalid_cursor, mixed_source_pagination_unsupported
401	missing_api_key, invalid_api_key
402	insufficient_history_credits
403	ip_not_allowed, invalid_status_transition (partner attempting LMN-owned transition), history_lookup_not_enabled, inspections_not_enabled
404	vehicle_not_found, order_not_found, order_vehicle_snapshot_not_found, history_lookup_not_found, inspection_not_found
409	invalid_status_transition, past_order_cutoff, past_secondary_inspection_cutoff, duplicate_order, DUPLICATE_INSPECTION
410	vehicle_unavailable
422	idempotency_key_reused
429	rate_limited, capacity_exceeded
500	internal_error
503	dealer_upstream_unavailable, service_unavailable

​

Per-code troubleshooting

Code	HTTP	Meaning	When	What to do
validation_error	400	Request shape failed validation.	Bad enum, missing field, model without make, ids > 100, from without to. Dealer requests: an auction-only filter such as auction_status sent with source=dealer.	Inspect error.details.issues[].path (or error.details.field). Fix the request; do not retry as-is. A future alias/suggestion release will add to rejected dealer model/sub_model errors (and rejected model on GET /v1/vehicles/trims) error.details.suggestions — { model, sub_model?, catalog_status, make? } entries to send instead; make appears only when a multi-value make request is rejected — and error.details.facets. Dealer cases: see Missing dealer listings.
missing_idempotency_key	400	Required Idempotency-Key header is absent.	POST /v1/orders, or a plate request to POST /v1/history-lookups, without the header. History VIN requests do not require it.	Keep one stable key per logical request and reuse it for retries.
invalid_cursor	400	Cursor invalid, expired, or sort-mismatched (orders and invoices).	Resending a cursor after changing sort= on GET /v1/orders or GET /v1/invoices. Not returned by GET /v1/vehicles: it can instead return 400 validation_error on cursor for an incompatible price sort or taxonomy version change. Legacy page-number cursors may silently apply their position to changed filters — see Missing dealer listings → T5. GET /v1/eagle-eye/watches/\{watch_id\}/matches reports a bad cursor as 400 validation_error with details.field: "cursor".	Restart pagination from page 1 with the desired sort.
missing_max_bid	400	Auction vehicle requires max_bid_amount_usd.	POST with null/omitted/below-listing bid.	Add max_bid_amount_usd (integer > 0, ≥ listing). Not required for buy-now.
missing_api_key	401	x-api-key header absent.	Any request without header.	Add the header.
invalid_api_key	401	Key not recognized, revoked, or wrong env.	Sandbox key against production URL, or revoked key.	Verify env (sandbox vs production); rotate if compromised.
ip_not_allowed	403	Source IP not in allowlist.	Egress IP missing from the key’s allowlist. Production keys only — sandbox trial keys have no allowlist and never return this.	Add the IP yourself: partner console → Keys → the key → Allowlist. Check egress NAT stability; if your backend has rotating IPs, certify on sandbox first.
invalid_status_transition	403 / 409	Requested transition not permitted.	403 = partner attempted an LMN-owned status (secondary_inspection_in_progress, secondary_inspection_ready, acquiring, secured, export_processing, in_transit); details.reason: "partner_not_authorized". 409 = sequence violation (e.g., delivered from non-customs, DELETE from non-placed); details.reason: "out_of_sequence". details.current_status set in both cases.	Re-fetch GET /v1/orders/{id} to see current state. Only use partner-permitted transitions: in_transit → customs, customs → delivered.
vehicle_not_found	404	Unknown or unavailable vehicle ID.	Stale ID, wrong-env ID, a dealer (encar_*) detail page whose upstream advertisement is no longer active / marked SOLD or WAIT, or a dealer listing currently under contract (계약중) on Encar.	Refresh the listing; confirm correct base URL. For a SOLD / WAIT dealer car, treat this as no longer available to buy and remove or disable the listing in your UI. For an under-contract dealer car, this is reversible — don’t remove the listing permanently; it can resolve normally again once the contract falls through. Cars you have already ordered are exempt — their detail still resolves from your stored order snapshot, so a purchased vehicle won’t return this error.
order_not_found	404	Unknown order ID for this key.	Wrong env, cross-key ID, or deleted.	Confirm correct base URL; the ID belongs to your account.
order_vehicle_snapshot_not_found	404	Order exists, but no purchased-vehicle snapshot is stored.	GET /v1/orders/{id}/vehicle for a historical order created before snapshot storage.	Use live GET /v1/vehicles/{vehicle_id} only if the listing still exists; otherwise contact LMN for manual recovery.
past_order_cutoff	409	POST after the auction’s cutoff.	auction_date − N min (your integration’s lead time; default 1440 = 24h) already passed.	Inform dealer that the order window is closed.
past_secondary_inspection_cutoff	409	POST with secondary_inspection_required: true after the inspection request window.	End of day (auction day − 2, your integration’s local time) already passed — read secondary_inspection_cutoff_at on the Vehicle resource.	Offer the dealer the same order without inspection (secondary_inspection_required: false) while order_cutoff_at is still open.
duplicate_order	409	Active order already exists for this vehicle.	Repeat POST while a prior order is not terminal. details.existing_order_id references it.	Redirect user to existing order page. Do not auto-retry.
idempotency_key_reused	422	An order key was reused with a different vehicle/inspection flag, or a History plate key with a different normalized body (including reference or fresh).	Reusing one key across different logical requests, or changing a retry body. History VIN keys are ignored.	Orders expose details.original_vehicle_id / details.original_secondary_inspection_required; History exposes details.original_lookup_id. Reuse the original key/body to recover that request, or intentionally create a new key for genuinely new work.
vehicle_unavailable	410	Vehicle no longer available.	Dealer or buy-now listing disappeared before LMN could complete the purchase.	Move order to failed in UI once the order snapshot reflects failure_reason: "vehicle_unavailable"; notify dealer.
rate_limited	429	Several conditions share this code — one permanent, the rest transient. See Telling the 429s apart.	Permanent: a sandbox trial key has spent its lifetime call budget. Transient: more than 5 test-webhook fires per minute on one Eagle Eye watch; more than 60 invoice PDF downloads per minute per key; a history-lookup cap (10 in flight, 200 per KST day).	Branch on error.details and Retry-After. details.used present → budget exhausted, stop retrying. Else Retry-After header present (invoice PDFs, history lookups) → wait that many seconds. Else → test-webhook throttle, retry after ~60s.
history_lookup_not_enabled	403	Vehicle history lookups are not enabled for your account in this environment.	POST /v1/history-lookups before production onboarding is complete.	Use sandbox, or contact LMN to be enabled for production.
history_lookup_not_found	404	Unknown lookup ID for this key.	Wrong env, another partner’s ID, or a mistyped hlk_ ID.	Confirm the base URL and that the lookup was created with your key.
inspections_not_enabled	403	The inspection API is not enabled for your account in this environment.	Any /v1/inspections request without the inspections_api feature.	Contact LMN to be enabled.
inspection_not_found	404	Unknown inspection ID for this key.	Wrong env, another partner’s inspection, or a mistyped id — in any status.	Confirm the base URL and that the inspection was created with your company’s key.
DUPLICATE_INSPECTION	409	Your company already requested an inspection for this car.	Repeat POST /v1/inspections for the same carUniqueId, in any status including ready. details.id is the existing inspection. Upper-case by design (shared with the CarbitX inspection code).	Read GET /v1/inspections/{id} with that id. Do not auto-retry.
capacity_exceeded	429	Global capacity for new real-data history work is temporarily full.	Enabled production or sandbox real-data trial admission; fixture-only examples do not use this provider capacity.	Honor Retry-After; retry the same VIN, or the same plate idempotency key/body.
insufficient_history_credits	402	No available credit for a new chargeable history lookup in this environment.	Production prepaid balance or sandbox test-credit balance is exhausted; an active free-repeat entitlement remains usable at zero balance.	Request more credits through the partner console. Do not loop retries expecting the balance to replenish automatically.
service_unavailable	503	The feature is not available in this environment, or is temporarily switched off.	POST /v1/history-lookups against production while the feature is closed. GET /v1/vehicles with trim, or GET /v1/vehicles/trims, while trim filtering is switched off (details.reason: "trim_filter_disabled"). GET /v1/vehicles/facets on a server that has not yet loaded any auction inventory (details.reason: "facets_cache_not_ready") or whose loaded inventory carries no auction taxonomy version (details.reason: "taxonomy_version_mismatch"); both carry details.retry_after_seconds: 60.	Use sandbox, or contact LMN. For trim_filter_disabled, drop trim (the rest of the search still works) or retry later. For the two facets reasons, keep your current facets copy and retry after details.retry_after_seconds.
internal_error	500	Server-side failure.	Rare; LMN on-call is paged automatically. Body carries only a generic message — no stack traces.	Retry with exponential backoff (3 tries). If persistent, share request_id with support.
mixed_source_pagination_unsupported	400	cursor passed with mixed auction+dealer source using an unsupported sort or multiple makes/models.	Trying to paginate beyond page 1 on a query like source=glovis,dealer&cursor=….	Restart pagination per source — issue separate requests with source=glovis and source=dealer. Mixed pagination is supported with sort=price_asc / price_desc and at most one make/model; other mixed sorts remain first page only. See also Missing dealer listings → T4.
dealer_upstream_unavailable	503	Every requested dealer source is unreachable or returned an invalid response, and no eligible Encar list cache exists.	Transient dealer-source outage, network blip, bot-protection interstitial, or extractor drift. Encar list search may return an exact cache page no more than 30 minutes old as source_status.encar.status: "stale". Since 2026-10-20, when Encar answers a dealer list read with a server error (HTTP 5xx), LMN retries that read once, about 0.4 seconds later, if enough of the request’s time budget remains (see the Changelog); a request can still return this 503 after that retry. Mixed requests can degrade gracefully, with two headers: X-LMN-Partial-Dealer-Unavailable: 1 and X-LMN-Dealer-Unavailable-Sources: <csv> for partial or unavailable sources.	Retry after a short backoff (5–30s). Preserve prior inventory state. If persistent (> 5 min for a single ID, > 2 min for list), include request_id and the failing dealer query in a support note — auction requests are unaffected during dealer outages. For price-sorted mixed pagination, a failure before any dealer row is examined can return this 503; retry the same cursor. Storefront handling: Missing dealer listings → T6.

​

History processing failure is separate from HTTP failure

A successful GET /v1/history-lookups/{id} returns HTTP200 even when the stored lookup has status: "failed". Inspect its failure.code (no_record, provider_unavailable, or provider_error), keep any available version-2 aggregate, and read per-provider sources. A failed primary lookup consumes no credit, including when supplemental Car365 or Encar facts are returned. Supplemental provider failure alone does not invalidate a ready primary report.

Network timeouts do not prove POST was rejected. Resume GET when you have the ID. A plate’s same idempotency key/body recovers the original job; a VIN repeat does so only while that job is in flight. If the original VIN lookup may have finished, locate it through GET-list, the accepted reference, identifier, and time range before intentionally submitting again. A completed VIN request can create a new lookup in expanded collection. A client timeout does not cancel the server job. See History integration.

​

Telling the 429s apart

429 rate_limited covers conditions with opposite remedies. Discriminate on the body and the Retry-After header:

	Test webhook throttle	Invoice PDF limit / history-lookup caps	Trial budget exhausted
Where	POST /v1/eagle-eye/watches/{watch_id}/test-webhook only	GET /v1/invoices/{invoice_id}/document (60/min per key); POST /v1/history-lookups (10 in flight, 200 per KST day)	Any authenticated /v1 endpoint
error.details	absent	limit, retry_after_seconds; history lookups also scope: in_flight or daily	{ "limit": 1000, "used": 1000 }
Retry-After header	not sent	sent (equals details.retry_after_seconds)	not sent
X-Quota-* headers	not set by this condition	not set by this condition	present
Clears on its own?	Yes — within 60 seconds	Yes — after Retry-After seconds (the daily history cap resets at the next KST midnight)	No — never
Correct response	Wait ~60s and retry	Wait Retry-After seconds and retry	Stop retrying; get more budget

if (res.status === 429) {
  const { error } = await res.json();
  if (error.details?.used != null) {
    // Lifetime budget spent. Retrying will never succeed.
    throw new QuotaExhausted(error.details);
  }
  const retryAfter = Number(res.headers.get('Retry-After'));
  // Invoice PDF limit or history-lookup cap: wait as told. Otherwise it is the
  // test-webhook throttle, which clears within a minute.
  await sleep((retryAfter > 0 ? retryAfter : 60) * 1000);
}

Do not write a blanket “429 → exponential backoff” handler, and do not treat every 429 with details.limit as permanent. Backoff loops forever on the budget case, and the daily history-lookup cap has a limit but clears at the next KST midnight. Use details.used for the budget and Retry-After for everything that clears.

​

Test webhook throttle

POST /v1/eagle-eye/watches/{watch_id}/test-webhook is limited to 5 fires per minute per watch, counted over a rolling 60-second window. Exceeding it returns:

{
  "error": {
    "code": "rate_limited",
    "message": "Test webhook limit reached (5/min per list) — try again in a minute",
    "request_id": "req_8829374"
  }
}

No details object, and no Retry-After. The window is rolling, so capacity returns gradually as older fires age out — waiting a full minute after the last accepted fire is always sufficient. This is the only throttle enforced on /v1; the fair-use targets in Authentication are not enforced server-side.

​

Trial budget exhausted

Sandbox keys minted from a trial (self-serve) account carry a lifetime call budget — 1,000 calls by default. When it runs out, every subsequent request returns 429:

{
  "error": {
    "code": "rate_limited",
    "message": "This trial key's 1000-call budget is exhausted. Request production access at console.lmnauto.com or contact [e-mail].",
    "request_id": "req_8829374",
    "details": { "limit": 1000, "used": 1000 }
  }
}

This is not a throttle, and backing off will not clear it. The budget is a lifetime total, not a per-minute or per-month window — it does not refill on its own. A client that treats 429 as “retry with exponential backoff” will retry forever. error.details.used being present is what distinguishes this from the transient 429s above, which do clear.

The API sends no Retry-After header on this response, because there is no time after which the request would succeed.

​

How to resolve it

Situation	Action
Still building, need more calls	Request production access in the console and say what you’re building. We can raise your sandbox budget without waiting for full approval.
Integration is ready	Request production access. Approval unlocks production key minting, and production keys carry no call budget.
Just need a few more calls now	Mint a new key (not rotate — see below). Trial accounts may hold 2 active sandbox keys, each with its own budget.

Rotating an exhausted key does not reset its budget. Rotation deliberately carries over both the budget and the calls already used, so the new key is exhausted the moment it’s created — otherwise rotation would be an unlimited free-budget loop. To get a fresh budget you must create a new key, which is a different button.

​

Staying ahead of it

Budgeted keys carry the remaining count on every response, including successful ones:

X-Quota-Limit: 1000
X-Quota-Remaining: 6

X-Quota-Remaining is computed after the current request is counted. Log it, or alert when it drops below a threshold, rather than waiting for the first 429.

Keys with no budget — every production key, plus any sandbox key whose budget has been lifted — send no quota headers at all. Absence means unlimited, not zero; a client that parses a missing header as 0 will lock itself out of a perfectly healthy production key.

​

Dealer pricing continuation

Dealer-inclusive vehicle cursors are signed and expire 24 hours after search creation. A malformed, expired, legacy or query/partner/environment-mismatched cursor returns 400 validation_error, details.field: "cursor", details.reason: "restart_required". Restart without a cursor; retain your own collected IDs for deduplication. Transient 503 responses may be retried with the same cursor while it remains valid.

Price-sorted dealer searches that expand beyond four make/model branches return 400 validation_error with details.reason: "search_too_broad". Omit make for a single all-makes branch, narrow the selection, or search separately. The number of inventory pages is not capped by this rule.

A price search that cannot advance within its source-call budget also returns 400 validation_error with details.reason=search_too_broad. Narrow the search or split the make/model selection; repeating the same cursor cannot resolve this limit. A mixed auction/dealer search with multiple make/model branches cannot continue, so it fails explicitly if it cannot establish its first page within the budget.

503 with details.reason=unsupported_source_configuration means price-sorted certified pricing is unavailable with the configured dealer sources. Contact support; retrying the same query does not change this configuration. Transient source failures retain retryable 503 behavior.