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, parameter, or request 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 exceeds the configured maximum.	No.
`429`	Authentication lockout or quota exceeded.	Yes — after `Retry-After`.
`500`	Unexpected server error.	Yes — with backoff.
`503`	Dependency unavailable or search safety timeout.	Yes — with backoff.

json

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

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

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. Every listing is live-priced from the continuous feed regardless; the block only reports the extra at-request bid re-read, which most listings do not qualify for. 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

An unfiltered search can page to any depth. A heavily filtered search is bounded by a per-query timeout rather than a hard offset, so a very deep, very narrow page can return 503. Narrow the filter or reduce offset rather than retrying the same URL.