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

Обрабатывайте 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)

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

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

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

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

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

Повторяйте только явно полученные временные 429/502/503/504. Ответ 429/503 означает, что платформа уже перебрала доступные маршруты, — делайте повтор с экспоненциальной задержкой, jitter и ограничением числа попыток, как в примере ниже. Запросы с hosted tools или генерацией изображений платформа может сознательно не повторять между маршрутами (защита от двойного списания) — в этом случае безопасно повторить тот же запрос со стороны клиента. Сетевой таймаут после отправки тела запроса может означать, что генерация уже началась: не повторяйте создающий POST вслепую.

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

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]);

async function requestWithBackoff(run: () => Promise<Response>) {
  for (let attempt = 0; attempt < 3; attempt += 1) {
    const response = await run();
    if (response.ok || !retryable.has(response.status)) return response;
    if (attempt === 2) return response;

    const retryAfter = Number(response.headers.get("retry-after"));
    const delay = Number.isFinite(retryAfter)
      ? retryAfter * 1000
      : 1000 * 2 ** attempt + Math.random() * 300;
    await new Promise((resolve) => setTimeout(resolve, delay));
  }
  throw new Error("unreachable");
}

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

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

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

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

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