Кодове на грешките
Всяка грешка на API-то е application/problem+json (RFC 7807) с едни и същи полета: type, title, status, code и, където има какво да се назове, detail. Адресът в type води до кода на тази страница.
{
"type": "https://magistrat.bg/api/errors/not_found",
"title": "Not found",
"status": 404,
"code": "not_found",
"detail": "no lawyer with that identifier"
}Разклонявайте кода си по HTTP статуса и по code — стабилен низ, който е и последният сегмент на type — никога по текста в title или detail.
400bad_request
Параметър не минава проверката — например числов параметър (page, pageSize, days) не е цяло число. Полето detail назовава параметъра и стойността.
Поправете параметъра, който detail назовава, и изпратете заявката отново.
400invalid_date
Дата не е във формат yyyy-MM-dd или денят е извън обхвата на архива с промените. Полето format носи очаквания формат.
Подайте датата като yyyy-MM-dd, например 2026-10-19.
400page_too_deep
Страницата е след първите 10 000 резултата. Полето maxPage назовава най-дълбоката: 10 000 / pageSize при документите на регистър и 500 при делата на адвокат или фирма.
Стеснете търсенето с филтър, период или по-точна заявка, вместо да обхождате по-дълбоко.
401api_key_required
Заявка към данни без ключ. Без ключ отговарят само документацията и тази страница.
Изпращайте ключа в заглавката X-Api-Key или като Authorization: Bearer. Ключ се издава от конзолата.
401invalid_api_key
Ключът е непознат, оттеглен или непълен. Оттегленият ключ спира да работи до минута.
Проверете в конзолата дали ключът е цял и активен; ако е оттеглен, създайте нов.
403banned
Заявките от този IP адрес са спрени за 24 часа, защото следват шаблона на автоматично изтегляне на данните на едро.
Спирането изтича само след 24 часа. Ако смятате, че е грешка, пишете ни на hello@magistrat.bg и посочете IP адреса.
404not_found
Документът, делото, адвокатът или фирмата с този идентификатор не съществува.
Проверете идентификатора — вземайте го от отговор на търсене или списък, вместо да го съставяте сами.
404unknown_registry
Няма регистър с такъв идентификатор (slug) в пътя на заявката.
Регистрите и идентификаторите им са в /api/registries.
429rate_limited
Лимитът в минута за ключа е пълен. Заглавката Retry-After казва след колко секунди има място, а X-RateLimit-* — колко остава.
Изчакайте Retry-After секунди и повторете; разпределете заявките равномерно във времето.
429quota_exceeded
Месечната квота на организацията е изчерпана — всички ключове теглят от нея. Retry-After брои до 00:00 UTC на първо число.
Изчакайте новия месец или изберете по-горно ниво от конзолата — то важи в рамките на минута.
500upstream_error
Инструмент на MCP сървъра не получи отговор от API-то.
Повторете извикването; ако грешката остане, пишете ни на hello@magistrat.bg.