Ошибки и статусы

Обрабатывайте HTTP-статус и машинный error.code, а не сравнивайте полный текст сообщения. Текст предназначен человеку и может уточняться.

{
  "error": {
    "message": "Безопасное описание ошибки",
    "type": "neuroapi_error",
    "code": "upstream_unavailable"
  }
}

Ошибки запроса — нужно действие с вашей стороны

Временная недоступность — повторяйте с backoff

Коды, которых нет в таблице, приводятся к ближайшему безопасному варианту по HTTP-статусу: 400/422 → upstream_invalid_request, 401/403/429 и 5xx → upstream_unavailable, всё остальное → internal_error.

Стабильность и перегрузки

Если вы часто видите 429/503 или ошибки перегрузки, проверьте тариф API-ключа: резервный маршрут и официальные каналы заметно снижают число сбоев.

Тариф «Смарт» (группа auto)

Делает ровно одну физическую попытку на экономичном «Пилоте». При безопасной для повтора (retryable) ошибке сразу запускает полную цепочку «Оптимального». Списание всегда идёт по группе успешной физической попытки, фиксированного коэффициента нет. Подходит большинству нагрузок: дешевле, когда всё стабильно, и живучее при перегрузках.

Тариф «Оптимальный» (группа plus)

Коммерческие официальные API-каналы — максимальная стабильность для продуктивных нагрузок, где важнее предсказуемость, чем экономия.

Переключение — в настройках API-ключа (группа токена). Ни один тариф не обещает ноль ошибок: резервный маршрут снижает число сбоев, но обрабатывать временные ошибки в коде всё равно нужно.

Когда повторять

Повторяйте временные ошибки только когда операция безопасна для повтора. Одного статуса 429/502/503/504 недостаточно: он не доказывает, что генерация не началась или что списание отменено. Для безопасных повторов используйте экспоненциальную задержку, jitter и ограничение числа попыток.

Запросы с hosted tools, сохранённым состоянием или генерацией изображений могут продолжать выполняться после потери соединения. Если платформа не повторила такой запрос из-за неизвестного результата, повтор со стороны клиента также может создать вторую платную работу. При provider_result_unknown или сетевом таймауте после отправки не повторяйте создающий POST автоматически. Если получили ID задачи, проверяйте её через GET; если ID нет, сохраните request id и обратитесь в поддержку.

Когда не повторять

400/422, цензура, неверные медиа и недостаток баланса требуют действия пользователя. Автоматический повтор только создаст лишнюю нагрузку.

Таймауты клиента

Не разрывайте соединение раньше времени — пока идёт ожидание, платформа сама перебирает маршруты, а у моделей со скрытым рассуждением (GPT-5.6, Claude) первый токен честно занимает минуты. Рекомендуемые таймауты на первый ответ: 120 секунд для лёгких моделей, 300 секунд для моделей с рассуждением, до 600 секунд для тяжёлых (Claude Opus, GPT-5.6 Sol), 360 секунд для генерации изображений. Клиент, отключающийся на 30–60 секундах, будет регулярно терять ответы, которые уже почти дошли.

const retryable = new Set([429, 502, 503, 504]);

// Только чтение состояния: эта функция не отправляет повторные POST.
async function getWithBackoff(url: string, headers: HeadersInit) {
  for (let attempt = 0; attempt < 3; attempt += 1) {
    const response = await fetch(url, { method: "GET", headers });
    if (response.ok || !retryable.has(response.status)) return response;
    if (attempt === 2) return response;

    const rawRetryAfter = response.headers.get("retry-after");
    const retryAfter = rawRetryAfter?.trim()
      ? (/^\d+$/.test(rawRetryAfter.trim())
        ? Number(rawRetryAfter)
        : (Date.parse(rawRetryAfter) - Date.now()) / 1000)
      : NaN;
    const delay = Number.isFinite(retryAfter) && retryAfter >= 0
      ? retryAfter * 1000 + Math.random() * 300
      : 1000 * 2 ** attempt + Math.random() * 300;
    if (delay > 30_000) return response;
    await response.body?.cancel();
    await new Promise((resolve) => setTimeout(resolve, delay));
  }
  throw new Error("unreachable");
}

Важно: для асинхронного видео действуют более строгие правила: если получен task ID или HTTP 202, повторять POST нельзя. Повторяйте только GET статуса или скачивания.

Медиа по внешней ссылке

Ссылка может быть недоступна, слишком медленна либо затронута сетевой фильтрацией и ТСПУ Роскомнадзора. Проверьте, что URL публичный и открывается без cookie/авторизации. Для небольших файлов надёжнее скачать их в приложении и передать Base64.

Информация: ошибка доставки ответа не всегда означает, что генерация не выполнялась. При неизвестном результате резерв может сохраняться до сверки. При спорном списании сохраните время, модель и request id и обратитесь в поддержку.

Полная таблица ошибок Alibaba Cloud, Images и Video →