Konfiguration und Fehler

Client konfigurieren

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:

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

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.

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.

Fehler behandeln

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.

Prüfen Sie dieselben Zugangsdaten unabhängig mit der CLI:

famulor doctor
famulor list-assistants --limit 10

HTTP-Verhalten und Scope-Anforderungen finden Sie in der REST-API-Referenz. Für KI-Werkzeugverbindungen nutzen Sie die MCP-Anleitung.

​Client konfigurieren

​OAuth-Zugriffstokens

​Timeouts und Abbruch

​Wiederholungsverhalten

​Fehler behandeln

​Fehlerbehebung

Client konfigurieren

OAuth-Zugriffstokens

Timeouts und Abbruch

Wiederholungsverhalten

Fehler behandeln

Fehlerbehebung