Ошибки, лимиты и безопасность

Каждая ошибка приходит с понятным кодом в поле detail. Ниже — что он означает и что делать.

Коды ответов

• 200 — всё хорошо.
• 400 — в запросе ошибка: не хватает поля или значение не подходит. Текст подскажет, что не так.
• 401 invalid_api_key — ключ неверный или отозван. Проверьте, что ключ скопирован полностью, вместе с bst_.
• 402 subscription_readonly — подписка не оплачена: данные можно читать, но не менять. Подписка и оплата
• 403 api_key_read_only — ключ «Только чтение» пытается изменить данные. Выпустите ключ «Чтение и изменение».
• 403 permission_denied — у сотрудника, выпустившего ключ, нет прав на этот раздел.
• 403 api_key_not_allowed_here — этот раздел ключу недоступен. Ключ работает только с данными: сделки, клиенты, автомобили, товары, работы, календарь, звонки, отчёты и справочники. Сотрудники, права, пароли, подписка и настройки — только через CRM в браузере.
• 404 — такой сделки, клиента или раздела нет (или он в точке, к которой у ключа нет доступа).
• 429 rate_limited — слишком много запросов. Подождите столько секунд, сколько указано в заголовке Retry-After.

Лимиты

• До 120 запросов в минуту на один ключ. Для отчётов загружайте данные страницами по 100 записей с паузой, а не все сразу.
• Вместо частых опросов «что нового?» используйте вебхуки — они приходят сами и не тратят лимит.

Безопасность

• Все запросы — только по https://.
• Ключ хранится только на вашем сервере. Не вставляйте его в код страниц, который видят посетители сайта, и не отправляйте в мессенджерах.
• Для каждой программы — свой ключ; ненужный сразу отзывайте. Как отозвать ключ
• Все изменения, сделанные через API, видны в «Действиях сотрудников» с пометкой названия ключа — всегда можно понять, что сделала программа.