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

Ошибка API — это ответ, в котором Chatterfy объясняет, почему не выполнил запрос. У всех ошибок одинаковый вид, поэтому разобраться можно по двум полям: коду ответа и code . В статье — как читать ошиб

Обновлено 2 ноября 2026 г.6 мин

Ошибка API — это ответ, в котором Chatterfy объясняет, почему не выполнил запрос. У всех ошибок одинаковый вид, поэтому разобраться можно по двум полям: коду ответа и code.

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

Как выглядит ошибка

Ошибка API приходит в JSON с объектом error: в нём type, code, message и request_id. Код HTTP-ответа показывает группу ошибки, а code — точную причину:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_limit",
    "message": "limit must not exceed 100",
    "request_id": "req_19b1e1109b0d37e463f571b01c2b5eba"
  }
}

Поле	Что это
`type`	Группа ошибки, например `invalid_request_error` или `authentication_error`
`code`	Короткое название конкретной ошибки. По нему ищите решение в таблицах ниже
`message`	Объяснение для человека. Формулировка может меняться, поэтому программе лучше смотреть на `code`
`request_id`	Номер запроса. Он есть в каждом ответе, в том числе успешном, — в заголовке `X-Request-Id`

Пишете в поддержку — пришлите request_id

По request_id поддержка найдёт ваш запрос за секунды. Добавьте к нему время запроса и адрес, на который вы его отправляли. Сам ключ не присылайте.

Быстрая диагностика: 400, 401, 403, 404

Код ответа	Что случилось	Что делать
`400`	Ошибка в запросе: не то поле, не тот формат, неверный фильтр	Прочитайте `message` — там написано, что не так. Исправьте тело запроса
`401`	Нет ключа, он неверный или уже заменён	Проверьте ключ и заголовок `ApiKey`
`403`	Ключ рабочий, но доступа нет: у роли нет нужного права или объект в другой компании либо в Space, куда аккаунт не добавлен	Выдайте сервисному аккаунту роль с нужным правом — Права API-ключа: какую роль выдать
`404`	Объекта с таким id нет	Проверьте id — берите его только из ответов API

Быстрая диагностика: 405, 409, 429, 500, 503

Код ответа	Что случилось	Что делать
`405`	У адреса нет такого метода	Проверьте метод: `GET`, `POST`, `PATCH` или `DELETE`
`409`	Действие конфликтует с текущим состоянием	Посмотрите `code` в таблице ниже
`429`	Слишком много запросов	Подождите столько секунд, сколько указано в `Retry-After`
`500`, `503`	Сбой на стороне Chatterfy	Повторите через несколько секунд. Не помогло — напишите в поддержку с `request_id`

Ошибки ключа и доступа: 401 и 403

`code`	Что значит	Что делать
`missing_api_key`	Заголовок `ApiKey` не передан	Добавьте заголовок `ApiKey: ВАШ_КЛЮЧ`. Заголовок `Authorization` не подходит
`invalid_api_key`	Ключ неверный, обрезан или уже заменён	Скопируйте ключ заново целиком. Если ключ меняли кнопкой Reissue key, вставьте новый — Как получить API-ключ
`access_denied`	Роли не хватает права на это действие	Сверьтесь с таблицей прав в статье Права API-ключа: какую роль выдать
`permissions_unavailable`	Не удалось проверить права — временный сбой	Повторите запрос через несколько секунд

Ошибки в теле запроса: 400

Ошибки 400 из-за тела запроса: оно пустое, не JSON, слишком большое или поле не прошло проверку.

`code`	Что значит	Что делать
`empty_body`	Тело запроса пустое	Передайте JSON, хотя бы `{}`
`invalid_body`	Тело — не JSON, JSON с ошибкой или поле не того типа, например текст вместо числа	Проверьте кавычки и запятые. Ключи и строки — только в двойных кавычках
`body_too_large`	Тело больше 64 КБ	Уменьшите запрос, например разбейте фильтр
`validation_failed`	Поле не прошло проверку: не тот формат, не то значение, слишком длинное	В `message` написано, какое поле и что не так
`missing_anchor`	Не передан обязательный id: `bot_id`, `chat_id` или `company_id`	Добавьте нужный id в тело запроса
`no_fields`	В `PATCH` не передано ни одного поля	Передайте хотя бы одно поле для изменения
`empty_message`	Сообщение без текста и без файлов	Передайте `content`, `files` или оба

Ошибки страниц, выгрузки и периода: 400

Ошибки 400 при листании страниц (limit, cursor), выгрузке чатов и запросе аналитики за период:

`code`	Что значит	Что делать
`invalid_limit`	`limit` меньше 1 или больше 100	Укажите `limit` от 1 до 100
`invalid_cursor`	`cursor` повреждён или собран вручную	Передавайте `next_cursor` из ответа без изменений
`cursor_out_of_range`	Поиск дошёл до 10 000-го чата	Используйте выгрузку — Как выгрузить все чаты через API — или разбейте список фильтром по `created_at`
`cursor_expired`	Между страницами выгрузки прошло больше 5 минут	Начните выгрузку заново без `cursor`
`invalid_range`, `range_too_wide`	В аналитике `to` раньше `from` или период длиннее 366 дней	Исправьте даты периода
`invalid_timezone`	Неизвестный часовой пояс	Укажите название вида `Europe/Moscow`

Ошибки фильтра чатов: 400

Коды ошибок фильтра начинаются с invalid_filter_ или unknown_filter_. В message указано место ошибки, например filter.filters[1], — это второе условие в группе (счёт идёт с нуля).

`code`	Что значит
`unknown_filter_field`	Такого поля нет. В `message` перечислены все доступные
`invalid_filter_operator`	Поле не поддерживает этот оператор. В `message` перечислены подходящие
`invalid_filter_value`	Значение не того типа: строка вместо списка, текст вместо числа, неверная дата
`invalid_filter_key`	Для `custom_fields` и `tracker_fields` не передан `key`, или передан не id поля
`invalid_filter_node`	Условие и группа перепутаны: в одном узле есть и `field`, и `filters`
`filter_too_large`, `filter_too_deep`	Больше 64 условий или больше 5 уровней вложенности

Все поля и операторы — в статье Фильтры чатов в API.

Ошибки в чужих id: тег, поле, ответственный

`code`	Что значит	Что делать
`unknown_tag`	Тег принадлежит другому боту	Возьмите id тегов из `GET /bots/v1/{bot_id}/tags` этого бота
`unknown_custom_field`	Поле принадлежит другому боту или передан `key` вместо id	Возьмите id из `GET /bots/v1/{bot_id}/custom-fields`
`unknown_assignee`	Человек не состоит в Space этого бота	Выберите участника из `POST /spaces/v1/{space_id}/members/search`
`unknown_reply_message`	Сообщение для ответа — из другого чата	Передайте id сообщения из того же чата
`..._not_found`	Объект не найден: `chat_not_found`, `bot_not_found`, `message_not_found` и другие	Проверьте id и права ключа
`unknown_endpoint`	Такого адреса нет	Проверьте адрес: версия идёт после ресурса, например `/chats/v1/search`

Конфликты: ошибка 409

`code`	Что значит
`space_not_empty`	Space нельзя удалить, пока в нём есть боты
`domain_already_exists`	Такой домен уже зарегистрирован на платформе
`domain_blocked`	Заблокированный домен нельзя изменить или удалить

Лимит запросов: 120 в минуту и ошибка 429

Каждый ключ может отправить 120 запросов в минуту. Лимит считается за последние 60 секунд, а не по календарным минутам. Точное значение для вашего ключа видно в колонке API key на странице Service accounts.

В каждом ответе есть заголовки, по которым видно, сколько осталось:

Заголовок	Что значит
`X-RateLimit-Limit`	Сколько запросов в минуту можно этому ключу
`X-RateLimit-Remaining`	Сколько запросов ещё осталось
`X-RateLimit-Reset`	Когда лимит восстановится — время в секундах Unix
`Retry-After`	Только в ответе `429`: сколько секунд подождать

Получили 429 rate_limit_exceeded — подождите Retry-After секунд и продолжайте. Не повторяйте запрос сразу: лимит от этого не восстановится быстрее.

Другие ограничения API

Что	Ограничение
Размер тела запроса	64 КБ
Размер заголовков	16 КБ
Время ответа	Если Chatterfy не успел ответить за 10 секунд, придёт `503 service_unavailable`
Записей на странице	До 100, по умолчанию 25
Глубина поиска чатов	10 000 чатов. Для большего — выгрузка
Cursor выгрузки	5 минут после каждой страницы
Период аналитики	До 366 дней
Текст сообщения	До 4096 символов
Вложений в сообщении	До 10