Skip to main content
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

​
code
string
Código de error legible por máquina, por ejemplo INVALID_REQUEST, UNAUTHORIZED, UPLOAD_FAILED.
​
message
string
Descripción legible por humanos.
​
status
number
Código de estado HTTP, si está disponible.
​
retryable
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).
​
details
unknown
Detalles proporcionados por el servidor, normalmente una lista de incidencias de Zod para errores de validación.

​
Códigos comunes

CódigoCausa¿Reintentable?
INVALID_REQUESTEl cuerpo de la solicitud no pasó la validación del esquema antes de enviarse.No
UNAUTHORIZEDFalta la clave de API o no es válida.No
NOT_FOUNDEl recurso no existe o no tienes acceso.No
CONFLICTConflicto de versión (HTTP 409).Sí
TOO_MANY_REQUESTSSe alcanzó el límite de tasa (HTTP 429).Sí
INTERNAL_SERVER_ERRORFallo transitorio del servidor (HTTP 500).Sí
IDEMPOTENT_REPLAY_IN_PROGRESSLa solicitud original sigue en ejecución con la misma clave de idempotencia (HTTP 202).Sí
INVALID_RESPONSEEl servidor devolvió un cuerpo que no coincidía con el esquema esperado.No
UPLOAD_FAILEDLa 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

​
code
'TASK_FAILED' | 'TASK_CANCELLED' | 'TASK_TIMED_OUT'
Se corresponde directamente con el estado terminal de la tarea.
​
message
string
O bien el mensaje de error de la tarea proporcionado por el servidor, o un fallback generado.
​
status
TaskStatus
El estado terminal de la tarea.
​
task
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