Ошибки и лимиты

Коды ответов

Код	Когда	Что делать
400	тело или параметры не прошли проверку	починить запрос; повтор не поможет
401	ключа нет, он отозван или недействителен	проверить заголовок и ключ
403	ключу не выдана нужная область доступа	выпустить ключ с нужной областью
404	вакансия не найдена или чужая	проверить vacancyId
429	превышен лимит запросов	подождать Retry-After секунд

Тело ошибки — стандартная форма Nest:

{ "statusCode": 403, "message": "Ключу не выдана нужная область доступа" }

Сообщения на русском и предназначены человеку, который читает логи. Ветвиться в коде по тексту не стоит — он может измениться; ветвитесь по коду ответа.

Почему 404, а не 403

Запрос к чужой вакансии отвечает «не найдено», а не «нет доступа». Иначе по коду ответа можно было бы перебирать идентификаторы и узнавать, что у другой компании существует, — то есть утечка получалась бы из самой формы отказа.

По той же причине 401 одинаков для «формат ключа не тот», «такого ключа нет», «ключ отозван» и «секрет не сходится».

Лимиты

600 запросов в минуту на чтение и 60 в минуту на приём откликов — на каждый ключ отдельно. Превышение даёт 429 с заголовком Retry-After в секундах.

Уважайте Retry-After: клиент, который повторяет запрос немедленно, держит лимит исчерпанным и делает хуже прежде всего себе. Полная выгрузка страницами по 200 записей в эти лимиты укладывается с большим запасом; если упираетесь — скорее всего, вы ходите за одним и тем же по кругу вместо инкрементальной синхронизации.

Что делать при сбоях

Ошибки 5xx и обрывы соединения — повторяйте с экспоненциальной задержкой. Приём откликов идемпотентен, поэтому повтор безопасен: дубля не будет.

Выгрузка идемпотентна по своей природе — повторный запрос той же страницы вернёт то же самое, пока данные не изменились.