Ошибки и повторные запросы

Любой ответ API тенанта (/v1) с кодом вне 2xx содержит JSON с понятным человеку полем message. Решения принимайте по HTTP-статусу, а не по тексту: сообщение предназначено для логов и людей и может меняться.

Тело ошибки

Формы две, в зависимости от того, какой слой отклонил запрос.

Шлюз и операции поискового движка. Проверки аутентификации, области ключа, тарифа, квоты и лимитов выполняются перед любой операцией. Операции, которые передаются поисковому движку (коллекции, документы, searchCollection, multiSearch, …), отвечают в той же простой форме:

{ "message": "Forbidden - this API key may not access the collection \"orders\"." }

Некоторые из них добавляют поля рядом с message:

Операции, которые реализует сама контрольная плоскость. Это события, рекомендации, подсказки, эксперименты, коннекторы, ассистенты, голос, медиа, семантический поиск и поиск по изображению. Они отвечают с несколькими дополнительными полями:

{
  "defined": false,
  "code": "CONFLICT",
  "status": 409,
  "message": "The experiment is already running.",
  "data": {}
}

code — стабильное имя статуса (BAD_REQUEST, UNAUTHORIZED, PAYMENT_REQUIRED, FORBIDDEN, NOT_FOUND, CONFLICT, TOO_MANY_REQUESTS, INTERNAL_SERVER_ERROR). В data лежат подробности, если они есть:

Контракт описывает общую часть: message (схема ApiResponse), а для 402 ещё available / requested (схема InsufficientCredits). Клиент, читающий message, работает с обеими формами. Числа сначала берите из data.available, затем, если его нет, из available верхнего уровня.

Коды статуса

API не возвращает 422. Ошибки валидации приходят как 400.

Конфликты

409 всегда означает «не в этом состоянии». Какое состояние мешает, сказано в сообщении:

Повторные запросы

• Соблюдайте Retry-After. Он есть в каждом 429 от квоты или лимита частоты, в секундах. Для месячной квоты это время до сброса, иногда дни. Покажите «квота исчерпана» вместо ожидания. Лимит AI-операций на сессию передаёт время ожидания в data.retry_after, а не в заголовке.
• На 500, 502 и 503 повторяйте с паузой. Паузу увеличивайте экспоненциально, со случайным разбросом, и остановитесь после нескольких попыток.
• Не повторяйте 400, 401, 403, 404, 411 и 413: тот же запрос завершится так же.
• Неудачные запросы не расходуют квоту. В месячную квоту идёт только успешный ответ поискового движка. Неудачный вызов модели не стоит кредитов, а его резерв освобождается.

Сгенерированные SDK выбрасывают типизированную ошибку для каждого статуса. По умолчанию они повторяют 408, 429 и 5xx с увеличением паузы и соблюдают Retry-After.

Идемпотентность

Повторная запись может выполниться дважды: первая попытка прошла, а ответ потерялся. Защиты две:

• Idempotency-Key в createConnector (POST /connectors). Передайте уникальное значение длиной до 255 символов. Повтор с тем же ключом и тем же телом вернёт исходный ответ, включая секрет коннектора, который показывается один раз. Тот же ключ с другим телом вернёт 409. Остальные операции заголовок игнорируют.
• event_id в событиях. ingestEvents отбрасывает событие с уже сохранённым event_id и учитывает его в deduplicated. Пакет безопасно отправить повторно, если у каждого события есть event_id (см. события).

У остальных операций записи ключа идемпотентности нет. Прежде чем повторять создание, проверьте, не выполнилась ли первая попытка, например через listExperiments.

У исходящей доставки событий своя политика повторов — шесть попыток с джиттером, и повторяются только 408, 429 и 5xx. См. Вебхуки.