Операции · 2026-09-01 · HippoAPI Documentation Team

Ошибки и повторы

Классифицируйте сбои API, собирайте полезные данные и повторяйте только временные запросы, которые можно безопасно повторить.

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

В ответах, отличных от 2xx, используется объект ошибки с удобочитаемым сообщением и может включать тип, код или идентификатор запроса. Рассматривайте статус HTTP как первый сигнал классификации и сохраняйте идентификатор запроса, если он присутствует.

{
  "error": {
    "message": "Error description (request id: ...)",
    "type": "new_api_error",
    "code": ""
  }
}

Коды состояния и действия

Status	Значение	Действие приложения
400	Неверный запрос, модель, поле или неподдерживаемый параметр.	Исправьте запрос. Не повторяйте одно и то же тело без изменений.
401	Ключ API отсутствует, имеет неверный формат, срок действия истек, отключен или недействителен.	Исправьте или поверните ключ. Не повторяйте попытку автоматически.
403	Учетная запись, ключ, IP-адрес, группа или модель не разрешены.	Просмотрите элементы управления доступом и доступность модели.
402	Баланса или квоты недостаточно.	Прежде чем отправлять дополнительные запросы, проверьте кошелек и квоту ключей.
404	Конечная точка или ресурс модели не найдены.	Проверьте базовый URL-адрес, путь к конечной точке и точный идентификатор модели.
429	Текущая частота запросов или параллелизм слишком высоки.	Откажитесь от джиттера и уменьшите параллелизм.
5xx	Сбой платформы или вышестоящего поставщика.	Повторите безопасные запросы со строгим лимитом попыток; сохраните идентификатор запроса.

Используйте ограниченную экспоненциальную отсрочку

Повторять только ошибки, которые могут быть временными: сбои подключения, HTTP 429 и выбранные ответы 5xx. Добавьте случайное дрожание, чтобы многие рабочие процессы не повторяли попытку одновременно. Установите максимальное количество попыток и общий срок.

const delaysMs = [500, 1000, 2000]

for (let attempt = 0; attempt <= delaysMs.length; attempt++) {
  try {
    return await callHippoAPI()
  } catch (error) {
    const status = error?.status
    const retryable = status === 429 || (status >= 500 && status < 600)
    if (!retryable || attempt === delaysMs.length) throw error
    const jitter = Math.floor(Math.random() * 250)
    await new Promise((resolve) => setTimeout(resolve, delaysMs[attempt] + jitter))
  }
}

Регистрируйте доказательства без регистрации секретов

Не регистрируйте заголовки Authorization, полные ключи API или полные запросы, содержащие личные, конфиденциальные или регулируемые данные. Отредактируйте их перед отправкой ошибок в инструменты наблюдения.

Временная метка UTC и идентификатор трассировки приложения.
Идентификатор запроса HippoAPI, если он присутствует.
Метод HTTP и путь к конечной точке.
Идентификатор модели, код состояния, продолжительность и повторная попытка.
Отредактированная сводка ошибок.

Прежде чем обращаться в службу поддержки

Воспроизведите проблему с наименьшим безопасным запросом, убедитесь, что модель отображается в GET/v1/models, и проверьте журналы использования. Затем предоставьте метку времени, конечную точку, модель, статус HTTP, идентификатор запроса и отредактированную сводку запроса на адрес [email protected].

Не указывайте свой ключ API. Если вы уже поделились или раскрыли его, отзовите его, прежде чем продолжить расследование.