Ошибки

SDK предоставляет два класса ошибок: YoukaRequestError для HTTP-ошибок и ошибок валидации, и YoukaTaskError для асинхронных задач, завершившихся в состоянии, отличном от успешного. Оба расширяют Error и содержат структурированные поля, чтобы вы могли ветвить логику по коду, статусу и возможности повтора.

`YoukaRequestError`

Выбрасывается при HTTP-ошибках, ошибках валидации запроса и некорректных ответах.

import { YoukaRequestError } from "@youka/sdk";

try {
  await client.projects.create(body);
} catch (error) {
  if (error instanceof YoukaRequestError) {
    console.error({
      code: error.code,
      message: error.message,
      status: error.status,
      retryable: error.retryable,
      details: error.details,
    });
  } else {
    throw error;
  }
}

Поля

string

Машиночитаемый код ошибки, например INVALID_REQUEST, UNAUTHORIZED, UPLOAD_FAILED.

string

Человекочитаемое описание.

number

HTTP-код статуса, если доступен.

boolean

true, если SDK считает, что ошибку имеет смысл повторить (лимиты запросов, временные ошибки сервера, идемпотентное повторение в процессе).

unknown

Детали от сервера; обычно список проблем Zod для ошибок валидации.

Частые коды

Код	Причина	Повторяемо?
`INVALID_REQUEST`	Тело запроса не прошло проверку схемы до отправки.	No
`UNAUTHORIZED`	Отсутствует или неверный API key.	No
`NOT_FOUND`	Ресурс не существует или у вас нет доступа.	No
`CONFLICT`	Конфликт версий (HTTP 409).	Yes
`TOO_MANY_REQUESTS`	Превышен лимит запросов (HTTP 429).	Yes
`INTERNAL_SERVER_ERROR`	Временный сбой сервера (HTTP 500).	Yes
`IDEMPOTENT_REPLAY_IN_PROGRESS`	Исходный запрос всё ещё выполняется с тем же ключом идемпотентности (HTTP 202).	Yes
`INVALID_RESPONSE`	Сервер вернул тело, не соответствующее ожидаемой схеме.	No
`UPLOAD_FAILED`	Загрузка по подписанному URL вернула не-2xx.	Зависит от status

`YoukaTaskError`

Выбрасывается из client.tasks.wait(...), client.projects.wait(...) и client.exports.wait(...), когда базовая задача или экспорт завершается в failed, cancelled или timed-out.

import { YoukaTaskError } from "@youka/sdk";

try {
  await client.projects.wait(created);
} catch (error) {
  if (error instanceof YoukaTaskError) {
    console.error({
      code: error.code,
      message: error.message,
      status: error.status,
      task: error.task,
    });
  } else {
    throw error;
  }
}

Поля

'TASK_FAILED' | 'TASK_CANCELLED' | 'TASK_TIMED_OUT'

Напрямую соответствует конечному статусу задачи.

string

Либо сообщение об ошибке задачи, предоставленное сервером, либо сгенерированное резервное.

TaskStatus

Конечный статус задачи.

RestTask

Полная полезная нагрузка задачи на момент сбоя. Полезно для логирования и пользовательских сообщений об ошибках.

Шаблон повторов

Комбинируйте retryable с ключом идемпотентности, чтобы построить безопасный цикл повторов:

import { YoukaRequestError } from "@youka/sdk";

async function createWithRetry<T>(fn: () => Promise<T>, maxAttempts = 3) {
  let lastError: unknown;

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error;
      if (
        error instanceof YoukaRequestError &&
        error.retryable &&
        attempt < maxAttempts
      ) {
        await new Promise((r) => setTimeout(r, 2 ** attempt * 1_000));
        continue;
      }
      throw error;
    }
  }

  throw lastError;
}

await createWithRetry(() =>
  client.projects.create(body, {
    idempotencyKey: "import-2026-04-08-song-001",
  }),
);

Всегда повторно используйте один и тот же ключ идемпотентности между попытками. Иначе сервер воспринимает повтор как новый запрос, и у вас могут появиться дубликаты.

Прерывание и отмена

Прерывание запроса выбрасывает стандартный AbortError, а не YoukaRequestError. Проверяйте его явно:

try {
  await client.projects.wait(created, { signal: controller.signal });
} catch (error) {
  if (error instanceof Error && error.name === "AbortError") {
    console.log("Cancelled by user");
    return;
  }
  throw error;
}

Что дальше

Tasks — хелперы ожидания и продвинутое опрашивание задач
Authentication — параметры конструктора и сигналы
API errors — те же коды в «сыром» HTTP

Overview

How To

Customization

Audio

Settings

Exporting

Account

`YoukaRequestError`

Поля

Частые коды

`YoukaTaskError`

Поля

Шаблон повторов

Прерывание и отмена

Что дальше

​YoukaRequestError

​Поля

​Частые коды

​YoukaTaskError

​Поля

​Шаблон повторов

​Прерывание и отмена

​Что дальше

`YoukaRequestError`

Поля

Частые коды

`YoukaTaskError`

Поля

Шаблон повторов

Прерывание и отмена

Что дальше