Reference

Errors & limits

Status codes, the error body shape, and which failures are worth retrying.

Errors use success: false and a sanitized error message. Log the X-Request-ID response header when reporting a failure — it is the only handle support has on a specific call.

Status	Meaning	Retry?
`400`	Invalid filter, pagination, source, unknown query parameter, or malformed body.	No — fix the request.
`401`	Missing, invalid, or expired API key.	No — repeated failures trigger a lockout.
`403`	Revoked key, or scope, IP, or origin denial.	No.
`404`	Source-aware resource not found.	No.
`409`	Ambiguous legacy identifier.	No — disambiguate with `site`.
`413`	Request body over 50 MB. Only reachable on the POST routes.	No.
`429`	Brute-force lockout (five failed authentications from your IP) or a rate/quota limit.	Yes — after `Retry-After`.
`500`	Unexpected server error (message is sanitized).	Yes — with backoff.
`503`	A dependency is unavailable, a search or facet query exceeded its safety timeout, a dataset has not been built yet, or authentication itself could not be verified (`Authentication is temporarily unavailable` — retry it; it is not a verdict on your key).	Yes — with backoff.

json

{
  "success": false,
  "error": "Unknown site 'ebay'. Valid sites: auto1, japan, copart, ecarstrade, encar, kbchachacha, openlane, schadeautos"
}

A 400 names the offending value and lists what would have been accepted.

Unknown query parameters are currently ignored, not rejected — do not rely on that. Each endpoint understands a fixed set of parameters, and one outside that set is on its way to becoming a 400 naming the offender. Send only what an endpoint documents, and treat a filter that seems to have no effect as a misspelling rather than an unsupported feature.

Failures that are not errors

Three responses look like something went wrong and have not. Handling them as errors is the most common integration bug:

A missing live_price block. It means the car is served at its cycle price, which for most listings is the only price there is. See Live prices.
details_pending: true. The upstream fetch is still running. Poll, do not retry in a tight loop.
An empty inspection_reports or images array. Most listings publish no reports, and a gallery that has not been vaulted yet reports its shortfall as pending.

Safety timeouts on deep filtered searches

/api/search and /api/listVehicles have no offset cap. A very deep filtered search is answered from a compact index where it can be; where it cannot, it is subject to the safety timeout and may come back 503 asking you to narrow it. Catalog, top-offers and classifieds listings are capped at offset 5000 — a deeper page is a 400 naming the limit. Narrow the filter rather than retrying the same URL.