Fehler

Das SDK stellt zwei Fehlerklassen bereit: YoukaRequestError für HTTP- und Validierungsfehler sowie YoukaTaskError für asynchrone Tasks, die in einem nicht erfolgreichen Zustand enden. Beide erweitern Error und enthalten strukturierte Felder, sodass du anhand von Code, Status und Wiederholbarkeit verzweigen kannst.

`YoukaRequestError`

Wird bei HTTP-Fehlern, Fehlern der Request-Validierung und fehlerhaften Responses ausgelöst.

import { YoukaRequestError } from "@youka/de/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;
  }
}

Felder

string

Maschinenlesbarer Fehlercode, zum Beispiel INVALID_REQUEST, UNAUTHORIZED, UPLOAD_FAILED.

string

Menschenlesbare Beschreibung.

number

HTTP-Statuscode, sofern verfügbar.

boolean

true, wenn das SDK den Fehler als einen erneuten Versuch wert erachtet (Rate Limits, vorübergehende Serverfehler, idempotente Wiederholung läuft).

unknown

Vom Server bereitgestellte Details, typischerweise eine Zod-Issue-Liste bei Validierungsfehlern.

Häufige Codes

Code	Ursache	Erneut versuchen?
`INVALID_REQUEST`	Request-Body hat die Schema-Validierung vor dem Senden nicht bestanden.	Nein
`UNAUTHORIZED`	Fehlender oder ungültiger API-Key.	Nein
`NOT_FOUND`	Ressource existiert nicht oder du hast keinen Zugriff.	Nein
`CONFLICT`	Versionskonflikt (HTTP 409).	Ja
`TOO_MANY_REQUESTS`	Rate Limit erreicht (HTTP 429).	Ja
`INTERNAL_SERVER_ERROR`	Vorübergehender Serverfehler (HTTP 500).	Ja
`IDEMPOTENT_REPLAY_IN_PROGRESS`	Die ursprüngliche Anfrage läuft unter demselben Idempotency-Key noch (HTTP 202).	Ja
`INVALID_RESPONSE`	Server hat einen Body zurückgegeben, der nicht zum erwarteten Schema passte.	Nein
`UPLOAD_FAILED`	Upload zur Signed URL hat Non-2xx zurückgegeben.	Hängt vom Status ab

`YoukaTaskError`

Wird von client.tasks.wait(...), client.projects.wait(...) und client.exports.wait(...) ausgelöst, wenn der zugrunde liegende Task oder Export in failed, cancelled oder timed-out endet.

import { YoukaTaskError } from "@youka/de/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;
  }
}

Felder

'TASK_FAILED' | 'TASK_CANCELLED' | 'TASK_TIMED_OUT'

Entspricht direkt dem terminalen Status des Tasks.

string

Entweder die vom Server bereitgestellte Task-Fehlermeldung oder ein generierter Fallback.

TaskStatus

Der terminale Task-Status.

RestTask

Das vollständige Task-Payload zum Zeitpunkt des Fehlers. Nützlich für Logging und nutzerseitige Fehlermeldungen.

Retry-Muster

Kombiniere retryable mit einem Idempotency-Key, um eine sichere Retry-Schleife zu bauen:

import { YoukaRequestError } from "@youka/de/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",
  }),
);

Verwende über alle Retry-Versuche hinweg immer denselben Idempotency-Key. Andernfalls behandelt der Server den Retry als neue Anfrage und du kannst am Ende Duplikate erhalten.

Abbruch und Cancellation

Beim Abbrechen einer Anfrage wird ein standardmäßiger AbortError ausgelöst — kein YoukaRequestError. Prüfe ihn explizit:

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

Was kommt als Nächstes

Tasks — Wait-Helper und erweitertes Task-Polling
Authentication — Konstruktoroptionen und Signale
API errors — dieselben Codes in rohem HTTP

Overview

How To

Customization

Audio

Settings

Exporting

Account

`YoukaRequestError`

Felder

Häufige Codes

`YoukaTaskError`

Felder

Retry-Muster

Abbruch und Cancellation

Was kommt als Nächstes

​YoukaRequestError

​Felder

​Häufige Codes

​YoukaTaskError

​Felder

​Retry-Muster

​Abbruch und Cancellation

​Was kommt als Nächstes

`YoukaRequestError`

Felder

Häufige Codes

`YoukaTaskError`

Felder

Retry-Muster

Abbruch und Cancellation

Was kommt als Nächstes