Перейти к содержимому
AISARAISAR

Ошибки

Формат ошибок, таблица статусов и рекомендации по повторным попыткам.

AISAR API возвращает ошибки в стандартном для Laravel формате JSON. Любая ошибка содержит как минимум поле message с человекочитаемым описанием.

Базовый формат
{
  "message": "Not found"
}

Ошибки валидации (422) дополнительно содержат поле errors — объект, где ключ это имя поля, а значение — массив сообщений об ошибках по этому полю:

Пример ошибки валидации
{
  "message": "The channel_id field is required.",
  "errors": {
    "channel_id": ["The channel_id field is required."]
  }
}

Таблица статусов

КодКогда возникает
200 OKЗапрос выполнен успешно (чтение или действие без создания ресурса, например POST /messages/send).
201 CreatedРесурс создан, например POST /v1/api-tokens.
401 UnauthorizedBearer-токен отсутствует, невалиден или отозван.
403 ForbiddenУ токена нет нужного разрешения (например conversation.create), либо на тарифе компании выключена нужная фича — тогда в теле дополнительно приходят error: "feature_not_available", feature и required_plan.
404 Not FoundРесурс не найден или не принадлежит компании токена (например, channel_id из другой компании).
422 Unprocessable EntityОшибка валидации тела запроса или логического ограничения (например, is_group: true для канала, где группы не поддерживаются).
429 Too Many RequestsПревышен лимит частоты запросов для токена (см. раздел «Аутентификация»).
5xxВнутренняя ошибка сервера. Не связана с содержимым вашего запроса.

Пример: ошибка прав доступа

Если у компании нет тарифа Business (фича api), запрос к API-эндпоинтам, требующим её, будет отклонён:

Ответ 403 — фича недоступна
{
  "message": "Feature not available on your plan.",
  "error": "feature_not_available",
  "feature": "api",
  "required_plan": "business"
}

required_plan вычисляется динамически — это slug самого дешёвого активного тарифа на продукте компании, который несёт нужную фичу, а не фиксированное значение. Для большинства фич из Business-набора (api, exports, deals, automations, …) это "business"; для фич, которых нет даже на Business (например voice_ai, voice_campaigns — только на тарифе Pro), это "pro". Значение может быть null, если ни один активный тариф на продукте компании не несёт эту фичу вообще.

Рекомендации по повторным попыткам

  • 401, 403, 404, 422 — не повторяйте запрос без изменений: сначала исправьте причину (токен, права, тело запроса, идентификатор ресурса).
  • 429 — повторите после retry_after секунд из тела ответа (или заголовка Retry-After); при повторных 429 увеличивайте задержку экспоненциально.
  • 5xx — временная проблема на стороне сервера, безопасно повторить с экспоненциальной задержкой (например 1с, 2с, 4с, 8с…). Для операций, создающих сущность (например, отправку сообщения), убедитесь, что запрос идемпотентен на вашей стороне, чтобы повтор не создал дубликат.