> ## Documentation Index
> Fetch the complete documentation index at: https://docs.youka.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Fehler

> YoukaRequestError, YoukaTaskError und erneut versuchbare Fehler behandeln

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.

```ts theme={null}
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

<ParamField path="code" type="string">
  Maschinenlesbarer Fehlercode, zum Beispiel `INVALID_REQUEST`, `UNAUTHORIZED`,
  `UPLOAD_FAILED`.
</ParamField>

<ParamField path="message" type="string">
  Menschenlesbare Beschreibung.
</ParamField>

<ParamField path="status" type="number">
  HTTP-Statuscode, sofern verfügbar.
</ParamField>

<ParamField path="retryable" type="boolean">
  `true`, wenn das SDK den Fehler als einen erneuten Versuch wert erachtet (Rate Limits, vorübergehende
  Serverfehler, idempotente Wiederholung läuft).
</ParamField>

<ParamField path="details" type="unknown">
  Vom Server bereitgestellte Details, typischerweise eine Zod-Issue-Liste bei Validierungsfehlern.
</ParamField>

### 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.

```ts theme={null}
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

<ParamField path="code" type="'TASK_FAILED' | 'TASK_CANCELLED' | 'TASK_TIMED_OUT'">
  Entspricht direkt dem terminalen Status des Tasks.
</ParamField>

<ParamField path="message" type="string">
  Entweder die vom Server bereitgestellte Task-Fehlermeldung oder ein generierter Fallback.
</ParamField>

<ParamField path="status" type="TaskStatus">
  Der terminale Task-Status.
</ParamField>

<ParamField path="task" type="RestTask">
  Das vollständige Task-Payload zum Zeitpunkt des Fehlers. Nützlich für Logging und
  nutzerseitige Fehlermeldungen.
</ParamField>

## Retry-Muster

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

```ts theme={null}
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",
  }),
);
```

<Tip>
  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.
</Tip>

## Abbruch und Cancellation

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

```ts theme={null}
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](/de/sdk/tasks) — Wait-Helper und erweitertes Task-Polling
* [Authentication](/de/sdk/authentication) — Konstruktoroptionen und Signale
* [API errors](/de/api/errors) — dieselben Codes in rohem HTTP