06 Guides

API error codes and retries

Every error is JSON with an error field and the fields that help to handle it.

The error body

HTTP 402

{
  "error": "quota_exhausted",
  "reset_at": "2026-11-01T00:00:00Z"
}

Possible fields: error, detail, reset_at, retry_after, markets, data_age_seconds.

HTTP	error	When
400	`bad_request`	A bad parameter, limit above the plan, offset given. The detail field explains.
401	`unauthorized`	No key, a wrong or revoked key, or the subscription has ended.
402	`quota_exhausted`	The period quota is spent; reset_at says when it renews.
403	`market_not_in_plan`	The market is not in the plan; markets lists those that are.
403	`feature_not_in_plan`	The change feed or live US search is not in the plan.
403	`invalid_signature · link_expired`	A photo link is forged or expired.
404	`not_found`	No such car or path.
429	`rate_limited`	More requests per second than the plan allows; retry_after.
502	`image_upstream_unavailable · invalid_image_upstream`	The source did not return the photo.
503	`upstream_unavailable · upstream_quota_exhausted · upstream_invalid_response`	Live US search: the provider is unavailable; retry_after.
500	`internal_error`	Our fault; admins are already alerted.

429 and 503 — retry after retry_after seconds (the same value is in the Retry-After header).
402 — retrying will not help before reset_at or a plan renewal: quota and limits.
400, 401, 403, 404 — fix the request, the key or the plan; a retry returns the same.
500 and 502 — one or two retries with a pause; we already see the error.