Errori

L’SDK espone due classi di errore: YoukaRequestError per errori HTTP e di validazione, e YoukaTaskError per task asincroni terminati in uno stato non riuscito. Entrambe estendono Error e includono campi strutturati così puoi diramare la logica in base a codice, stato e possibilità di retry.

`YoukaRequestError`

Generato per errori HTTP, errori di validazione della richiesta e risposte malformate.

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

Campi

string

Codice di errore leggibile dalla macchina, ad esempio INVALID_REQUEST, UNAUTHORIZED, UPLOAD_FAILED.

string

Descrizione leggibile dall’uomo.

number

Codice di stato HTTP, se disponibile.

boolean

true se l’SDK considera l’errore meritevole di un retry (rate limit, errori transitori del server, rigioco idempotente in corso).

unknown

Dettagli forniti dal server, tipicamente un elenco di issue Zod per errori di validazione.

Codici comuni

Codice	Causa	Ritentabile?
`INVALID_REQUEST`	Il body della richiesta non ha superato la validazione dello schema prima dell’invio.	No
`UNAUTHORIZED`	Chiave API mancante o non valida.	No
`NOT_FOUND`	La risorsa non esiste o non hai accesso.	No
`CONFLICT`	Conflitto di versione (HTTP 409).	Sì
`TOO_MANY_REQUESTS`	Raggiunto il limite di richieste (HTTP 429).	Sì
`INTERNAL_SERVER_ERROR`	Errore transitorio del server (HTTP 500).	Sì
`IDEMPOTENT_REPLAY_IN_PROGRESS`	La richiesta originale è ancora in esecuzione con la stessa chiave di idempotenza (HTTP 202).	Sì
`INVALID_RESPONSE`	Il server ha restituito un body che non corrispondeva allo schema atteso.	No
`UPLOAD_FAILED`	L’upload su Signed URL ha restituito un non-2xx.	Dipende dallo status

`YoukaTaskError`

Generato da client.tasks.wait(...), client.projects.wait(...) e client.exports.wait(...) quando il task o l’export sottostante termina in 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;
  }
}

Campi

'TASK_FAILED' | 'TASK_CANCELLED' | 'TASK_TIMED_OUT'

Corrisponde direttamente allo stato finale del task.

string

Il messaggio di errore del task fornito dal server oppure un fallback generato.

TaskStatus

Lo stato finale del task.

RestTask

Il payload completo del task al momento del fallimento. Utile per logging e messaggi di errore rivolti all’utente.

Pattern di retry

Combina retryable con una chiave di idempotenza per costruire un ciclo di retry sicuro:

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

Riutilizza sempre la stessa chiave di idempotenza tra i retry. Altrimenti il server tratta il retry come una nuova richiesta e potresti finire con duplicati.

Interruzione e cancellazione

L’interruzione di una richiesta genera un AbortError standard — non un YoukaRequestError. Verificalo esplicitamente:

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

Cosa fare dopo

Tasks — helper di attesa e polling avanzato dei task
Authentication — opzioni del costruttore e signal
API errors — gli stessi codici in HTTP raw

Overview

How To

Customization

Audio

Settings

Exporting

Account

`YoukaRequestError`

Campi

Codici comuni

`YoukaTaskError`

Campi

Pattern di retry

Interruzione e cancellazione

Cosa fare dopo

​YoukaRequestError

​Campi

​Codici comuni

​YoukaTaskError

​Campi

​Pattern di retry

​Interruzione e cancellazione

​Cosa fare dopo

`YoukaRequestError`

Campi

Codici comuni

`YoukaTaskError`

Campi

Pattern di retry

Interruzione e cancellazione

Cosa fare dopo