**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:

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

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

## Codes

| 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](https://apiauto.space/en/docs/endpoints/live/): the provider is unavailable; retry_after. |
| 500 | `internal_error` | Our fault; admins are already alerted. |

## When to retry

- 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](https://apiauto.space/en/docs/limits/) .
- 400, 401, 403, 404 — fix the request, [the key](https://apiauto.space/en/docs/auth/) or the plan; a retry returns the same.
- 500 and 502 — one or two retries with a pause; we already see the error.

---

Page: https://apiauto.space/en/docs/errors/