Конверт, ошибки, страницы
Единый формат ответа, коды отказов, курсорная выборка и пределы.
На этой странице
Конверт ответа #
Удачный ответ всегда кладёт содержимое в data — даже когда это один объект. У списков рядом появляются nextCursor и hasMore. Отказ приходит в том же конверте полем error с машинным кодом и пояснением на английском.
Все ответы идут с Cache-Control: no-store: в них чужая переписка.
{"data": { … }}
{"data": [ … ], "nextCursor": "2026-08-22T09:15:04.281Z", "hasMore": true}
{"error": {"code": "validation_error", "message": "content must not exceed 4096 characters"}}Коды отказов #
| HTTP | code | Когда |
|---|---|---|
| 400 | validation_error | тело не разобралось или значение не подходит |
| 401 | unauthorized | ключа нет, отозван или чужой |
| 403 | insufficient_scope | у ключа нет права на метод |
| 404 | not_found | разговора нет либо он другого сайта |
| 409 | conversation_closed | разговор закрыт, ответа посетитель не увидит |
| 409 | no_visitor | в разговоре нет посетителя виджета |
| 413 | file_too_large | файл по ссылке больше предела |
| 429 | rate_limit_exceeded | превышен предел частоты, смотрите Retry-After |
| 502 | file_fetch_failed | файл по вашей ссылке не скачался |
| 503 | storage_unavailable | база или Redis недоступны, повторите позже |
Страницы #
Выборка курсорная, а не по номерам страниц: пока читается первая страница, посетители пишут, и нумерация сдвинула бы часть разговоров мимо читающего. Курсор — время последнего показанного элемента в формате RFC 3339 с наносекундами.
Берите nextCursor из ответа и передавайте его параметром cursor, пока hasMore истинно.
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
| limit | int | нет | размер страницы: 25 по умолчанию, 100 потолок |
| cursor | string | нет | продолжение выборки: значение nextCursor предыдущего ответа |
Пределы #
| Что | Сколько |
|---|---|
| Запросов на ключ | 300 в минуту, дальше 429 с Retry-After |
| Размер страницы | 25 по умолчанию, 100 потолок |
| Длина ответа | 4096 символов |
| Тело запроса | 256 КБ |
| Файл по ссылке | 50 МБ |
| Срок подписанной ссылки на вложение | 1 час |
| Ожидание вашего обработчика вебхука | 20 секунд |
| Попыток доставки вебхука | 3, пауза 5 секунд и дальше вдвое |
| Окно проверки подписи вебхука | 5 минут |