Ошибки Developer API и лимиты запросов

Обновлено: 11 ноября 2026 · 6 мин чтения

Шаги

1. 1

   Формат ошибки

   Ошибки токена, scope, лимита и пути имеют одинаковый формат:

   {
     "error": {
       "code": "insufficient_scope",
       "message": "This action needs the messages:send permission.",
       "required_scopes": ["messages:send"],
       "request_id": "3f9c2a1e-8b7d-4c6a-9e15-2d4b7a0c9f31"
     }
   }

   code не меняется, в коде проверяйте именно его. message предназначен для человека и может меняться, с Accept-Language: en приходит на английском. В ответе 403 есть также заголовок WWW-Authenticate. Собственные проверки эндпоинта (обязательное поле, неверное значение) пока возвращают ошибку в старом формате, обычно с 422: { "error": "..." } или { "message": "...", "attributes": [...] }. Ошибки /oauth/* приходят в формате OAuth: { "error": "invalid_client" }.

2. 2

   Ошибки токена и разрешений

   • 401 invalid_token: токена нет, он не распознан или отозван. Проверьте заголовок: Authorization: Bearer clomni_pat_xxx.
   • 401 token_expired: срок истёк. Личный токен действует 30-365 дней, токен приложения 1 час.
   • 403 insufficient_scope: в токене нет scope. Посмотрите required_scopes, добавьте scope в приложение и отправьте на review (проверку), после одобрения создайте новый токен и выберите этот scope.
   • 403 endpoint_not_available: этот эндпоинт закрыт для токенов разработчика, его нет в API reference.
   • 403 app_not_approved: у приложения не осталось одобренных scope.
   • 403 app_suspended: Clomni приостановил приложение или приложение архивировано. Посмотрите причину в письме.
   • 403 app_owner_not_admin: владелец приложения больше не администратор workspace. Когда роль вернут, всё снова заработает.
   • 403 installation_owner_not_admin: человек, который подключил публичное приложение, больше не администратор, приложение нужно подключить заново.
   • 403 account_suspended: workspace приостановлен, работает только workspace:read.
3. 3

   Другие ошибки

   • 400 invalid_request: путь или параметр неверный (например limit вне диапазона 1-100).
   • 402 ai_credit_spent: AI-кредит workspace закончился (POST /ai_agents/{ai_agent_id}/ask). Не повторяйте автоматически.
   • 404 not_found: объекта нет, или он относится к другому workspace. 404 test_channel_missing: тестовый канал не создан.
   • 403 test_channel_webhook: для тестового канала нельзя указать адрес вебхука. 403 sandbox_restricted: в старом sandbox отправка наружу закрыта.
   • 409 conflict: второй экспорт одновременно с первым. 409 idempotency_key_reused: тот же Idempotency-Key пришёл с другим телом. 409 idempotency_key_in_progress: запрос с тем же ключом ещё выполняется.
   • 422: собственная проверка эндпоинта, например второй контакт с тем же e-mail. Исправьте тело.
   • 500 internal_error: ошибка на нашей стороне. Повторите чуть позже, а если ошибка повторяется, напишите нам с request_id.

   Отправка сообщения асинхронная: когда в WhatsApp закрыто 24-часовое окно или канал не подключён, запрос принимается, а потом сообщение получает статус failed. Причина находится в поле content_attributes.external_error сообщения. Если в WhatsApp QR приходит ограничение на новые диалоги (463), не отправляйте повторно: каждая попытка продлевает ограничение.

4. 4

   Когда можно повторять

   • 400, 401, 403, 404, 422: не повторяйте, сначала устраните причину.
   • 429: подождите столько секунд, сколько указано в заголовке Retry-After.
   • 500, 502, 503, 504 и ошибка сети: с растущей паузой (1, 2, 4, 8 секунд и случайная добавка), не больше 5 раз.

   Повторяя POST, передавайте Idempotency-Key, чтобы сообщение не ушло дважды.

5. 5

   Лимиты запросов

   • Общий: 300 запросов в минуту на токен.
   • Все токены приложения вместе: 600 запросов в минуту. Если создать много токенов, лимит не увеличится.
   • GET /sync/*: 60 в минуту на токен.
   • POST /conversations/{conversation_id}/messages: 60 в минуту на токен.
   • POST /oauth/token: 20 в минуту на client_id и IP.
   • POST /exports: 1 задача одновременно на workspace, 6 в день.

   В каждом ответе /v1, кроме /v1/me и /v1/oauth/*, есть заголовки RateLimit-Limit, RateLimit-Remaining и RateLimit-Reset (секунды). Когда RateLimit-Remaining приближается к нулю, замедлитесь.

6. 6

   Если пришёл 429

   При превышении лимита приходит 429 rate_limited с заголовком Retry-After. Пока это время не прошло, не отправляйте запросы с тем же токеном. Если заголовка нет, ждите с растущей паузой. Не запрашивайте список заново каждую минуту: получайте изменения вебхуками, а пропущенное забирайте через updated_since. Обновляйте токен приложения, когда он истекает, а не перед каждым запросом. Если нужен лимит выше, напишите на [email protected]: приложение, эндпоинт, ожидаемый объём и причина.

   Лимит API не отменяет собственный лимит канала: у номера WhatsApp Business API есть дневной лимит и рейтинг качества от Meta, а номер WhatsApp QR могут заблокировать за слишком много сообщений или за нежелательные сообщения.