Skip to main content
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 ausgelöst bei HTTP-Fehlern, Fehlern in der Request-Validierung und fehlerhaften Responses. 
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;
  }
}

​
Felder

​
code
string
Maschinenlesbarer Fehlercode, zum Beispiel INVALID_REQUEST, UNAUTHORIZED, UPLOAD_FAILED.
​
message
string
Menschenlesbare Beschreibung.
​
status
number
HTTP-Statuscode, falls verfügbar.
​
retryable
boolean
true, wenn das SDK den Fehler als wiederholenswert einstuft (Rate Limits, vorübergehende Serverfehler, idempotente Wiederholung läuft gerade).
​
details
unknown
Vom Server gelieferte Details, typischerweise eine Zod-Issue-Liste bei Validierungsfehlern.

​
Häufige Codes

CodeUrsacheWiederholbar?
INVALID_REQUESTRequest-Body hat die Schema-Validierung vor dem Senden nicht bestanden.No
UNAUTHORIZEDFehlender oder ungültiger API-Key.No
NOT_FOUNDRessource existiert nicht oder du hast keinen Zugriff.No
CONFLICTVersionskonflikt (HTTP 409).Yes
TOO_MANY_REQUESTSRate Limit erreicht (HTTP 429).Yes
INTERNAL_SERVER_ERRORVorübergehender Serverfehler (HTTP 500).Yes
IDEMPOTENT_REPLAY_IN_PROGRESSDie ursprüngliche Anfrage läuft unter demselben Idempotency-Key noch (HTTP 202).Yes
INVALID_RESPONSEServer hat einen Body zurückgegeben, der nicht zum erwarteten Schema passte.No
UPLOAD_FAILEDUpload über Signed URL hat einen Non-2xx-Status zurückgegeben.Depends on status

​
YoukaTaskError

Wird aus 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/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

​
code
'TASK_FAILED' | 'TASK_CANCELLED' | 'TASK_TIMED_OUT'
Entspricht direkt dem terminalen Status des Tasks.
​
message
string
Entweder die vom Server bereitgestellte Task-Fehlermeldung oder ein generierter Fallback.
​
status
TaskStatus
Der finale Task-Status.
​
task
RestTask
Die vollständige Task-Payload zum Zeitpunkt des Fehlschlags. 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/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 Wiederholungsversuche hinweg immer denselben Idempotency-Key. Andernfalls behandelt der Server den Retry als neue Anfrage und du kannst am Ende Duplikate erzeugen.

​
Abbruch und Canceln

Das Abbrechen einer Anfrage wirft ein normales AbortError — kein YoukaRequestError. Prüfe explizit darauf: 
try {
  await client.projects.wait(created, { signal: controller.signal });
} catch (error) {
  if (error instanceof Error && error.name === "AbortError") {
    console.log("Vom Benutzer abgebrochen");
    return;
  }
  throw error;
}

​
Wie geht’s weiter

  • Tasks — Wait-Helper und erweitertes Task-Polling
  • Authentication — Konstruktor-Optionen und Signals
  • API errors — dieselben Codes in rohem HTTP