Ошибки и надёжность интеграции
Коды ответа
| Код | Значение | Что делать |
|---|---|---|
| 200 / 201 | Запрос выполнен / ресурс создан | Прочитать тело ответа |
| 202 | Работа принята в очередь | Проверять состояние по идентификатору |
| 401 | Ключ отсутствует, истёк, отозван или владелец потерял доступ | Проверить ключ и членство |
| 402 | Недостаточно бюджета или превышен лимит тарифа | Прочитать причину и проверить лимиты пространства |
| 403 | Недостаточно прав, ключ только на чтение, требуется 2FA | Проверить роль и настройки ключа |
| 404 | Объект не найден или недоступен | Проверить пространство и идентификатор |
| 410 | Файл истёк или удалён из хранилища | Подготовить новую выгрузку |
| 422 | Некорректные поля или невозможное действие | Прочитать message, code и errors |
| 429 | Частота обращений превышена | Подождать Retry-After |
| 5xx | Временный сбой сервера | Повторить чтение с увеличением паузы |
Типичная ошибка содержит message для человека и code для программы. Валидация дополнительно возвращает errors с ошибками полей. Не привязывайте программу к русскому тексту сообщения.
Ошибки лимитов содержат объяснение недоступного ресурса. Положительный баланс не отменяет максимальное число сайтов, параллельных задач или выключенный перерасход. Как работают лимиты.
Пагинация
Большинство списков используют page и per_page. Ответ содержит data и параметры страницы. Не все методы одинаковы: история выгрузок, например, использует limit, а прямой endpoint каталога: курсор. Читайте контракт конкретного метода и не полагайтесь на одинаковую обёртку.
Для прогонов: per_page до 100; фильтры site_id, schedule_id, status, trigger, include_trials. Для прокси: per_page до 200 и pool_id. История выгрузок: limit до 100.
Повторы и тайм-ауты
Для GET применяйте нарастающую паузу с небольшим случайным сдвигом. Не повторяйте ошибку прав или валидации бесконечно. POST запуска может успеть выполниться до разрыва соединения: перед повтором проверьте историю.
Не опрашивайте долгий прогон каждую миллисекунду: 3–5 секунд обычно достаточно. Остановите опрос после конечного состояния. Ограничьте число повторов и сообщайте оператору причину отказа.
Удаление
DELETE может затрагивать связанные данные. Перед удалением сохраните нужный результат и проверьте идентификатор. Ключ только на чтение блокирует любые POST, PUT, PATCH и DELETE, включая команды, которые ничего не сохраняют, например проверку исходника.