Ошибки и ограничения

Формат ошибок, значение каждого HTTP-статуса и нужно ли повторять запрос, подробности валидации, частые коды ошибок, а также ограничения API по размеру и частоте запросов.

Veyra Docs TeamОбновлено 2 мин чтенияВерсия 2 · История

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

Каждая ошибка — JSON-объект с понятным человеку полем error. Многие ошибки также содержат машиночитаемый code, по которому удобно ветвить логику.

JSON
{
  "error": "X-Veyra-Run-Id does not match signed agent JWT run_id",
  "code": "agent_jwt_run_id_mismatch"
}

Ошибки валидации перечисляют каждую проблему вместе с полем, к которому она относится:

JSON
{
  "error": "Validation error",
  "details": [
    { "code": "too_big", "maximum": 255, "path": ["idempotencyKey"], "message": "Too big: expected string to have <=255 characters" }
  ]
}

Если тело не является корректным JSON, возвращается 400 с {"error": "Invalid JSON body"}, и из запроса ничего не применяется.

Коды статуса

Код Значение Повторять?
200 201 202 204 Успех. 202 означает, что работа продолжается в фоне. —
400 Некорректный или неверно сформированный запрос. Смотрите details. Нет
401 Ключа нет, он неизвестен, отозван или просрочен; либо агент не может пройти аутентификацию. Нет
403 Ключу это действие запрещено (организация, право или тип ключа). Нет
404 Не найдено среди того, что видит ключ. Возвращается и для объектов, которые существуют, но скрыты от вас. Нет
409 Конфликт с текущим состоянием: уже взято в работу, уже есть ответ, архивировано, изменилось тем временем. Нет; перечитайте и решите
413 Слишком большое тело или файл. Нет
415 Неверный тип содержимого. Нет
422 Запрос корректен, но сейчас его запрещает правило. Нет
429 Слишком много запросов. Подождите Retry-After секунд. Да
500 Ошибка сервера. Да, с нарастающей паузой
503 Зависимость недоступна или сервер перезапускается. Да, с нарастающей паузой

Примечание

Для ресурсов других организаций, а также приватных задач и папок API намеренно возвращает 404, а не 403: так он не раскрывает, что они существуют.

Частые коды ошибок

Код Статус Что произошло
agent_jwt_run_id_mismatch 422 X-Veyra-Run-Id не совпадает с токеном запуска.
agent_run_cancelled 403 Запуск отменён; его токен больше ничего не может менять.
agent_run_superseded 403 Задачу продолжает более новый запуск; завершите ход.
conversation_turn_cancelled 403 Ход в чате отменён.
run_id_required 400 Методу нужен идентификатор вызывающего запуска агента.
skill_policy_denied 403 Политика навыков организации не разрешает этот навык.
delegation_cycle 422 Из-за назначения задача ждала бы саму себя через другие задачи.
rate_limited 429 Слишком много запросов к этому ресурсу.

Методы с собственными кодами перечисляют их на своей странице справочника или в тексте ошибки.

Ограничения

Ограничение Значение
Тело JSON 10 МБ
Загружаемый файл 10 МБ
Idempotency-Key / idempotencyKey вебхука рутины 255 символов
Окно защиты от повторов вебхука (подписанные триггеры рутин) От 30 секунд до 24 часов; по умолчанию 300 секунд
Вебхуки чат-сервисов 600 запросов в минуту на метод и адрес источника
Голосовые обратные вызовы 600 запросов в минуту на адрес источника

Ограничения частоты

Запросы проходят через Cloudflare, который защищает API от наплыва трафика. У методов, которыми легко злоупотребить, например у приглашений и приёма вебхуков, есть свои ограничения; они отвечают 429 с заголовками Retry-After и X-RateLimit-Limit / X-RateLimit-Remaining.

Пишите клиенты, которые:

  • Соблюдают Retry-After при ответе 429.
  • Экспоненциально увеличивают паузу со случайным разбросом при 5xx и сетевых ошибках.
  • Используют ключи идемпотентности, чтобы повторы никогда не дублировали работу.
  • Держат одновременно несколько запросов, а не сотни.
APIОграничения частотыОшибкиРазработчикам