Errores

El SDK expone dos clases de error: YoukaRequestError para fallos HTTP y de validación, y YoukaTaskError para tareas asíncronas que terminaron en un estado no exitoso. Ambas extienden Error e incluyen campos estructurados para que puedas ramificar según el código, el estado y si es reintentable.

`YoukaRequestError`

Se lanza para errores HTTP, fallos de validación de la solicitud y respuestas malformadas.

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;
  }
}

Campos

string

Código de error legible por máquina, por ejemplo INVALID_REQUEST, UNAUTHORIZED, UPLOAD_FAILED.

string

Descripción legible por humanos.

number

Código de estado HTTP, si está disponible.

boolean

true si el SDK considera que merece la pena reintentar el error (límites de tasa, errores transitorios del servidor, repetición idempotente en curso).

unknown

Detalles proporcionados por el servidor, normalmente una lista de incidencias de Zod para errores de validación.

Códigos comunes

Código	Causa	¿Reintentable?
`INVALID_REQUEST`	El cuerpo de la solicitud no pasó la validación del esquema antes de enviarse.	No
`UNAUTHORIZED`	Falta la clave de API o no es válida.	No
`NOT_FOUND`	El recurso no existe o no tienes acceso.	No
`CONFLICT`	Conflicto de versión (HTTP 409).	Sí
`TOO_MANY_REQUESTS`	Se alcanzó el límite de tasa (HTTP 429).	Sí
`INTERNAL_SERVER_ERROR`	Fallo transitorio del servidor (HTTP 500).	Sí
`IDEMPOTENT_REPLAY_IN_PROGRESS`	La solicitud original sigue en ejecución con la misma clave de idempotencia (HTTP 202).	Sí
`INVALID_RESPONSE`	El servidor devolvió un cuerpo que no coincidía con el esquema esperado.	No
`UPLOAD_FAILED`	La subida a la URL firmada devolvió un estado no 2xx.	Depende del estado

`YoukaTaskError`

Se lanza desde client.tasks.wait(...), client.projects.wait(...) y client.exports.wait(...) cuando la tarea o exportación subyacente termina en failed, cancelled o 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;
  }
}

Campos

'TASK_FAILED' | 'TASK_CANCELLED' | 'TASK_TIMED_OUT'

Se corresponde directamente con el estado terminal de la tarea.

string

O bien el mensaje de error de la tarea proporcionado por el servidor, o un fallback generado.

TaskStatus

El estado terminal de la tarea.

RestTask

La carga útil completa de la tarea en el momento del fallo. Útil para logs y mensajes de error orientados al usuario.

Patrón de reintento

Combina retryable con una clave de idempotencia para construir un bucle de reintento seguro:

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",
  }),
);

Reutiliza siempre la misma clave de idempotencia en los reintentos. De lo contrario, el servidor trata el reintento como una nueva solicitud y puedes acabar con duplicados.

Interrupción y cancelación

Interrumpir una solicitud lanza un AbortError estándar — no un YoukaRequestError. Compruébalo explícitamente:

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;
}

Qué sigue

Tasks — helpers de espera y sondeo avanzado de tareas
Authentication — opciones del constructor y señales
API errors — los mismos códigos en HTTP en bruto

Overview

How To

Customization

Audio

Settings

Exporting

Account

`YoukaRequestError`

Campos

Códigos comunes

`YoukaTaskError`

Campos

Patrón de reintento

Interrupción y cancelación

Qué sigue

​YoukaRequestError

​Campos

​Códigos comunes

​YoukaTaskError

​Campos

​Patrón de reintento

​Interrupción y cancelación

​Qué sigue

`YoukaRequestError`

Campos

Códigos comunes

`YoukaTaskError`

Campos

Patrón de reintento

Interrupción y cancelación

Qué sigue