Getting started

Errors

Status codes follow HTTP semantics. The body is JSON in one of three shapes, so read the field that is present instead of relying on a single one.

Status	Meaning	Retry?
`200`	Success. An empty result is still `200` with `data: []` or `count: 0`.	—
`400`	The search engine rejected the query, or an export `limit`/`scroll_time` is above the maximum.	No, fix the request
`403`	Key, subscription, IP or source access problem. Also an invalid export cursor.	No
`404`	Vehicle, listing or dictionary entry not found in your source scope, or an expired export cursor.	No
`422`	Validation failed. `errors` names each field.	No, fix the fields
`503`	Search is temporarily unavailable. Honor `Retry-After` (seconds).	Yes, after the delay
`429` / `5xx`	Upstream or infrastructure failure. The body can be HTML.	Yes, with bounded backoff

Body shapes

Shape	Used for
`{"error": "…"}`	Access and lookup failures. Often echoes context such as `car_id`, `vin`, `domain_id` or `ip`.
`{"errors": {"field": ["…"]}}`	Validation. `message` is present on some endpoints and missing on others. Messages follow `lang`.
`{"message": "…"}`	Export limit errors (with `your_value` and `default_value`) and framework failures.

There is no fixed requests-per-minute limit on the public routes, but account and upstream limits can still apply. Always respect Retry-After when it is present.

Error handling with retries

# --retry repeats 429 and 5xx responses and honors Retry-After.
# --fail-with-body exits non-zero on 4xx/5xx but still prints the JSON.
curl -sg --fail-with-body --retry 3 \
  "https://api.lotarius.com/search?perPage=1&api_key=$CARS_API_KEY" \
  -H "Accept: application/json"

422 · perPage=1Live

{
  "errors": {
    "perPage": [
      "The per page field must be at least 2."
    ]
  }
}