Ошибки и ограничения
Формат ошибок, значение каждого HTTP-статуса и нужно ли повторять запрос, подробности валидации, частые коды ошибок, а также ограничения API по размеру и частоте запросов.
Формат ошибок
Каждая ошибка — JSON-объект с понятным человеку полем error. Многие ошибки также содержат машиночитаемый code, по которому удобно ветвить логику.
{
"error": "X-Veyra-Run-Id does not match signed agent JWT run_id",
"code": "agent_jwt_run_id_mismatch"
}Ошибки валидации перечисляют каждую проблему вместе с полем, к которому она относится:
{
"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и сетевых ошибках. - Используют ключи идемпотентности, чтобы повторы никогда не дублировали работу.
- Держат одновременно несколько запросов, а не сотни.