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

# Konfiguration und Fehler

> Authentifizierung, Workspace-Zugriff, eigene Domains, Anfragesteuerung und Fehlerbehebung

## Client konfigurieren

```typescript theme={null}
import { Famulor } from 'famulor-sdk';

const client = new Famulor({
  apiKey: process.env.FAMULOR_API_KEY,
  baseUrl: 'https://app.famulor.io/api/v1',
  timeoutMs: 90_000,
  maxRetries: 2,
});
```

| Option | Standard | Zweck |
| - | - | - |
| `apiKey` | — | Workspace-API-Schlüssel. Verwenden Sie genau eine Option: diese oder `accessToken`. |
| `accessToken` | — | OAuth-Zugriffstoken oder Funktion, die synchron oder asynchron eines zurückgibt. |
| `baseUrl` | `https://app.famulor.io/api/v1` | Vollständige API-Basis-URL einschließlich `/api/v1`. Verwenden Sie HTTPS für Ihre gehostete Anwendung. |
| `timeoutMs` | `90000` | Zeitlimit für die gesamte Anfrage einschließlich Authentifizierung, Wiederholungen, Wartezeiten und Lesen der Antwort, in Millisekunden. |
| `maxRetries` | `2` | Maximale Anzahl zusätzlicher Versuche für geeignete Leseanfragen. `0` deaktiviert Wiederholungen. |
| `fetch` | Laufzeit-`fetch` | Optionale kompatible Fetch-Implementierung für Serverintegrationen oder Tests. |

Das SDK liest Umgebungsvariablen nicht selbst. In diesen Beispielen übergibt Ihre Anwendung die Zugangsdaten aus `process.env`.

## OAuth-Zugriffstokens

Für eine Anwendung im Auftrag eines Benutzers übergeben Sie `accessToken` statt `apiKey`. Eine Callback-Funktion kann vor einer Anfrage das aktuelle Token abrufen:

```typescript theme={null}
import { Famulor } from 'famulor-sdk';

const client = new Famulor({
  accessToken: async () => {
    const token = process.env.FAMULOR_ACCESS_TOKEN;
    if (!token) throw new Error('An OAuth access token is required.');
    return token;
  },
});

const { data } = await client.assistants.list({ limit: 10 });
console.log(data.length);
```

Dieses Beispiel liest ein Token, das dem Server bereits bereitgestellt wurde. Ersetzen Sie die Abfrage für eine produktive Integration durch Ihren serverseitigen Token-Speicher und Ihre Erneuerungslogik. Das SDK führt weder die OAuth-Zustimmung noch die Token-Erneuerung aus. Siehe [Anforderungen an OAuth-Clients](/de/api-reference/introduction).

OAuth-Anfragen berücksichtigen die aktuelle Workspace-Mitgliedschaft, Rolle und genehmigten Scopes des Benutzers. API-Schlüssel folgen ihrem eigenen Workspace, Status und ihren Scopes. Beide benötigen API-Zugriff. Übergeben Sie nicht beide Zugangsdatenoptionen.

## Timeouts und Abbruch

Die Client-Standardwerte gelten für jede Operation. Übergeben Sie `timeoutMs`, `maxRetries` oder `signal` im letzten Argument nach den Methodeneingaben, um eine einzelne Anfrage anzupassen. Bei generierten `client.api`-Methoden ist es das zweite Argument; bei Ressourcen-Kurzmethoden kann es an erster, zweiter oder dritter Stelle stehen. Siehe [Beispiele für Anfrageoptionen](/de/sdk/usage#eine-einzelne-anfrage-anpassen). Das Zeitlimit gilt für die gesamte Anfrage einschließlich Token-Abruf, Wiederholungen, Wartezeiten und Lesen der Antwort. Mit einem `AbortSignal` kann Ihre Anwendung früher abbrechen.

```typescript theme={null}
const controller = new AbortController();

const pending = client.calls.list(
  { limit: 10 },
  { signal: controller.signal, timeoutMs: 10_000, maxRetries: 0 },
);

controller.abort();

try {
  await pending;
} catch (error) {
  if (!controller.signal.aborted) throw error;
}
```

Ein Abbruch beendet das Warten auf die Antwort. Er macht eine vom Server bereits angenommene API-Aktion nicht rückgängig.

## Wiederholungsverhalten

Geeignete **GET- und HEAD-Anfragen** können nach einem Netzwerkfehler oder HTTP `429`, `502`, `503` oder `504` wiederholt werden. Das SDK berücksichtigt vorhandene `Retry-After`-Angaben und verwendet sonst begrenzte, steigende Wartezeiten.

**Schreibanfragen werden niemals automatisch wiederholt**, auch nicht nach einer Ratenbegrenzung. Ein höheres `maxRetries` aktiviert keine Schreibwiederholungen. So werden Aktionen wie Anrufe, Nachrichten und Ressourcenkäufe vor versehentlicher Duplizierung geschützt.

<Warning>
  Nach einem Timeout oder Verbindungsverlust bei einer Schreibanfrage kann das Ergebnis unbekannt sein. Prüfen Sie Ressourcenstatus, Anrufverlauf oder Webhook, bevor Sie die Aktion wiederholen. Ein beliebiger Idempotenz-Header macht nicht jede Operation sicher wiederholbar.
</Warning>

## Fehler behandeln

```typescript theme={null}
import {
  Famulor,
  FamulorApiError,
  FamulorNetworkError,
  FamulorTimeoutError,
} from 'famulor-sdk';

const client = new Famulor({ apiKey: process.env.FAMULOR_API_KEY });

try {
  const { data } = await client.assistants.list({ limit: 10 });
  console.log(data.length);
} catch (error) {
  if (error instanceof FamulorApiError) {
    console.error({
      status: error.status,
      code: error.code,
      message: error.message,
      requestId: error.requestId,
      retryAfter: error.retryAfter,
    });
  } else if (error instanceof FamulorTimeoutError) {
    console.error('Request timed out.', error.mayHaveExecuted);
  } else if (error instanceof FamulorNetworkError) {
    console.error('Network request failed.', error.mayHaveExecuted);
  } else {
    throw error;
  }
}
```

| Fehler | Bedeutung |
| - | - |
| `FamulorApiError` | Die API hat einen Fehler zurückgegeben. Prüfen Sie `status`, `code`, `message`, `requestId` und optional `retryAfter` in Sekunden. |
| `FamulorNetworkError` | Es konnte keine Antwort abgerufen werden. `mayHaveExecuted` zeigt an, dass eine Schreibanfrage den Server bereits erreicht haben kann. |
| `FamulorTimeoutError` | Das SDK-Timeout ist abgelaufen. Diese Klasse erweitert `FamulorNetworkError`; prüfen Sie sie zuerst, wenn Sie Timeouts separat behandeln. |
| `FamulorAbortError` | Ihr `AbortSignal` hat die Anfrage abgebrochen. Eine bereits angenommene Schreibaktion kann trotzdem ausgeführt werden. |
| `FamulorResponseError` | Die Antwort kann nicht gelesen werden oder besitzt nicht die erwartete Paginierungsstruktur. Prüfen Sie `mayHaveExecuted`, bevor Sie eine Schreibaktion wiederholen. |
| `FamulorError` | SDK-Basisfehler, auch für ungültige lokale Konfiguration oder Anfrageparameter. |

Protokollieren Sie keine Zugangsdaten oder vollständigen sensiblen Anfrageinhalte. Eine vorhandene Anfrage-ID hilft dem Support, die fehlgeschlagene Anfrage zu finden.

## Fehlerbehebung

| Symptom | Was Sie prüfen sollten |
| - | - |
| `401` | Prüfen Sie, ob der richtige Schlüssel oder ein aktuelles OAuth-Token übergeben wird und nicht widerrufen oder abgelaufen ist. |
| `403 api_access_required` | Aktivieren Sie API-Zugriff über den Workspace-Tarif oder ein Add-on. |
| Anderes `403` | Prüfen Sie die benötigten Scopes, die Benutzerrolle und den Funktionszugriff des Workspaces. Das SDK umgeht diese Prüfungen nicht. |
| `404` | Prüfen Sie, ob die ID im Workspace der Zugangsdaten existiert. Ressourcen anderer Workspaces sind nicht zugänglich. |
| `429` | Beachten Sie `retryAfter`, reduzieren Sie Parallelität und vermeiden Sie häufiges Polling. Weitere Schlüssel erhöhen das gemeinsame Workspace-Limit nicht. |
| Anruferstellung schlägt fehl | Prüfen Sie aktiven Assistenten, ausgehend nutzbare Rufnummer, ausreichende Credits und die Zulässigkeit des gewünschten Ziels. |
| Netzwerk- oder Timeout-Fehler nach einer Schreibanfrage | Prüfen Sie vor einer Wiederholung, ob die Aktion ausgeführt wurde. |
| Browser-Import wird abgelehnt | Verschieben Sie das SDK in Ihr Backend. Für Website-Gespräche verwenden Sie das [Web-Widget](/de/web-widget). |

Prüfen Sie dieselben Zugangsdaten unabhängig mit der [CLI](/de/cli/overview):

```bash theme={null}
famulor doctor
famulor list-assistants --limit 10
```

HTTP-Verhalten und Scope-Anforderungen finden Sie in der [REST-API-Referenz](/de/api-reference/introduction). Für KI-Werkzeugverbindungen nutzen Sie die [MCP-Anleitung](/de/mcp/overview).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.