---
title: "Errors & limits"
description: "Status codes, the error body shape, and which failures are worth retrying."
canonical: "https://thecarapi.com/docs/errors"
contract_version: "2026-08-19"
api_base: "https://api.thecarapi.com"
source: "https://thecarapi.com/docs/errors.md"
---

# 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](https://thecarapi.com/docs/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.