06 Руководства
Коды ошибок API и повторы
Любая ошибка — JSON с полем error и полями, которые помогают её обработать.
Тело ошибки
{
"error": "quota_exhausted",
"reset_at": "2026-11-01T00:00:00Z"
}Возможные поля: error, detail, reset_at, retry_after, markets, data_age_seconds.
Коды
| HTTP | error | Когда |
|---|---|---|
| 400 | bad_request | Неверный параметр, limit выше тарифа, передан offset. Поле detail объясняет. |
| 401 | unauthorized | Нет ключа, ключ неверный, отозван или подписка закончилась. |
| 402 | quota_exhausted | Квота периода исчерпана; reset_at — когда обновится. |
| 403 | market_not_in_plan | Рынок не входит в тариф; markets — какие входят. |
| 403 | feature_not_in_plan | Лента изменений или живой поиск США не входят в тариф. |
| 403 | invalid_signature · link_expired | Ссылка на фото подделана или устарела. |
| 404 | not_found | Нет такой машины или пути. |
| 429 | rate_limited | Больше запросов в секунду, чем позволяет тариф; retry_after. |
| 502 | image_upstream_unavailable · invalid_image_upstream | Источник не отдал фото. |
| 503 | upstream_unavailable · upstream_quota_exhausted · upstream_invalid_response | Живой поиск США: поставщик недоступен; retry_after. |
| 500 | internal_error | Ошибка у нас; администраторы уже знают. |
Когда повторять
- 429 и 503 — повторите через retry_after секунд (то же значение — в заголовке Retry-After).
- 402 — повтор не поможет до reset_at или до продления тарифа: квота и лимиты.
- 400, 401, 403, 404 — исправьте запрос, ключ или тариф; повтор вернёт то же.
- 500 и 502 — один-два повтора с паузой; ошибка уже у нас на виду.