Справочник

Грешки и лимити

Кодове на отговор, формата на тялото при грешка и кои откази си струва да се опитат отново.

Грешките използват success: false и изчистено съобщение error. Записвайте заглавката на отговора X-Request-ID, когато съобщавате за проблем — тя е единствената връзка на поддръжката с конкретно извикване.

Статус	Значение	Повторен опит?
`400`	Невалиден филтър, страниране, източник, непознат параметър на заявката или неправилно тяло.	Не — поправете заявката.
`401`	Липсващ, невалиден или изтекъл API ключ.	Не — повторните неуспехи задействат блокиране.
`403`	Отменен ключ или отказ по обхват, IP или произход.	Не.
`404`	Ресурсът според източника не е намерен.	Не.
`409`	Двусмислен наследен идентификатор.	Не — уточнете със `site`.
`413`	Тяло на заявката над 50 MB. Възможно само при маршрутите с POST.	Не.
`429`	Блокиране срещу налучкване (пет неуспешни удостоверявания от вашия IP) или лимит на заявките/квотата.	Да — след `Retry-After`.
`500`	Неочаквана грешка на сървъра (съобщението е изчистено).	Да — с изчакване.
`503`	Зависимост не е достъпна, заявка за търсене или фасети е надвишила защитното време, набор от данни още не е изграден или самото удостоверяване не може да бъде проверено (`Authentication is temporarily unavailable` — опитайте отново; това не е присъда за ключа ви).	Да — с изчакване.

json

{
  "success": false,
  "error": "Unknown site 'ebay'. Valid sites: auto1, japan, copart, encar, kbchachacha, openlane, schadeautos"
}

Отговорът 400 посочва неправилната стойност и изброява какво би било прието.

Непознатите параметри на заявката в момента се игнорират, а не се отказват — не разчитайте на това. Всеки ендпойнт разбира фиксиран набор от параметри и такъв извън него е на път да стане 400 с посочено име. Изпращайте само това, което ендпойнтът документира, и третирайте филтър, който сякаш няма ефект, като правописна грешка, а не като неподдържана функция.

Откази, които не са грешки

Три отговора изглеждат така, сякаш нещо се е объркало, но не е. Обработването им като грешки е най-честият бъг при интеграция:

Липсващ блок live_price. Означава, че колата се обслужва с цената от цикъла, която за повечето обяви е единствената цена. Вижте Актуални цени.
details_pending: true. Извличането от източника още върви. Проверявайте периодично, не опитвайте отново в плътен цикъл.
Празен масив inspection_reports или images. Повечето обяви не публикуват протоколи, а галерия, която още не е архивирана, отчита недостига си като pending.

Защитни изтичания на времето при дълбоки филтрирани търсения

/api/search и /api/listVehicles нямат ограничение на отместването. Много дълбоко филтрирано търсене се обслужва от компактен индекс, където е възможно; където не е, подлежи на защитното изтичане на времето и може да върне 503 с молба да го стесните. Обявите в каталога, топ офертите и обявите на дребно са ограничени до отместване 5000 — по-дълбока страница е 400 с посочен лимит. Стеснете филтъра, вместо да опитвате отново същия адрес.