Configuration et erreurs

Configurer un client

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	Valeur par défaut	Fonction
`apiKey`	—	Clé API de l’espace de travail. Utilisez cette option ou `accessToken`, jamais les deux.
`accessToken`	—	Jeton OAuth ou fonction qui en renvoie un de manière synchrone ou asynchrone.
`baseUrl`	`https://app.famulor.io/api/v1`	URL de base complète, avec `/api/v1`. Utilisez HTTPS pour votre application hébergée.
`timeoutMs`	`90000`	Délai global de la requête, incluant l’authentification, les répétitions, les pauses et la lecture de la réponse, en millisecondes.
`maxRetries`	`2`	Nombre maximal de tentatives supplémentaires pour les lectures éligibles. `0` désactive les répétitions.
`fetch`	`fetch` de l’environnement	Implémentation Fetch compatible facultative pour les intégrations serveur ou les tests.

Le SDK ne lit pas lui-même les variables d’environnement. Dans ces exemples, votre application transmet l’identifiant depuis process.env.

Jetons d’accès OAuth

Pour une application agissant au nom d’un utilisateur, fournissez accessToken à la place de apiKey. Une fonction peut récupérer le jeton courant avant une requête :

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);

Cet exemple lit un jeton déjà fourni au serveur. Pour une intégration en production, remplacez cette lecture par votre stockage de jetons et votre logique de renouvellement côté serveur. Le SDK ne réalise ni le consentement OAuth ni le renouvellement des jetons. Voir Exigences des clients OAuth. Les requêtes OAuth suivent l’appartenance actuelle de l’utilisateur à l’espace de travail, son rôle et les portées approuvées. Les clés API suivent leur propre espace de travail, statut et portées. Accès API est requis dans les deux cas. Ne fournissez pas les deux options d’authentification.

Délais et annulation

Les valeurs du client s’appliquent à toutes les opérations. Passez timeoutMs, maxRetries ou signal dans le dernier argument, après les entrées de la méthode, pour adapter une requête. Pour les méthodes générées de client.api, il s’agit du deuxième argument ; les raccourcis de ressources peuvent le placer en première, deuxième ou troisième position. Voir Exemples d’options de requête. Le délai couvre toute la requête, y compris la récupération du jeton, les répétitions, les pauses et la lecture de la réponse. Un AbortSignal permet à votre application de l’annuler plus tôt.

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;
}

Annuler arrête l’attente de la réponse. Cela n’annule pas une action déjà acceptée par le serveur.

Répétition des requêtes

Les requêtes GET et HEAD éligibles peuvent être répétées après un problème réseau ou HTTP 429, 502, 503 ou 504. Le SDK respecte Retry-After lorsqu’il est présent et utilise sinon des délais croissants bornés. Les écritures ne sont jamais répétées automatiquement, même après une limitation de débit. Augmenter maxRetries n’active pas les répétitions d’écriture. Cela protège les appels, messages et achats de ressources contre les doublons accidentels.

Un délai dépassé ou une connexion perdue après une écriture peut laisser son résultat inconnu. Vérifiez l’état de la ressource, l’historique des appels ou le webhook avant de répéter l’action. Un en-tête d’idempotence arbitraire ne rend pas toutes les opérations répétables sans risque.

Traiter les erreurs

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;
  }
}

Erreur	Signification
`FamulorApiError`	L’API a renvoyé une erreur. Consultez `status`, `code`, `message`, `requestId` et éventuellement `retryAfter` en secondes.
`FamulorNetworkError`	Aucune réponse n’a pu être obtenue. `mayHaveExecuted` indique qu’une écriture a peut-être déjà atteint le serveur.
`FamulorTimeoutError`	Le délai du SDK est dépassé. Cette classe étend `FamulorNetworkError` ; testez-la d’abord si vous traitez les délais séparément.
`FamulorAbortError`	Votre `AbortSignal` a annulé la requête. Une écriture déjà acceptée peut néanmoins s’exécuter.
`FamulorResponseError`	La réponse ne peut pas être décodée ou ne possède pas la structure de pagination attendue. Vérifiez `mayHaveExecuted` avant de répéter une écriture.
`FamulorError`	Erreur de base du SDK, également utilisée pour une configuration locale ou des paramètres invalides.

Ne journalisez ni identifiants ni corps de requête sensibles complets. Un ID de requête, lorsqu’il existe, aide l’assistance à retrouver l’échec.

Dépannage

Symptôme	Vérification
`401`	Vérifiez que la bonne clé ou un jeton OAuth actuel est fourni, sans révocation ni expiration.
`403 api_access_required`	Activez Accès API via le forfait de l’espace de travail ou un module complémentaire.
Autre `403`	Vérifiez les portées requises, le rôle et les fonctionnalités autorisées. Le SDK ne contourne pas ces contrôles.
`404`	Confirmez que l’ID existe dans l’espace de travail de l’identifiant. Une ressource d’un autre espace est inaccessible.
`429`	Respectez `retryAfter`, réduisez la concurrence et évitez des lectures trop fréquentes. Des clés supplémentaires n’augmentent pas le budget commun.
Échec de création d’appel	Vérifiez l’assistant actif, son numéro compatible avec les appels sortants, les crédits et la destination autorisée.
Erreur réseau ou délai après une écriture	Vérifiez si l’action a eu lieu avant de la répéter.
Import navigateur refusé	Placez le SDK dans votre backend. Pour les conversations sur un site, utilisez le Widget web.

Vérifiez indépendamment les mêmes identifiants avec la CLI :

famulor doctor
famulor list-assistants --limit 10

Consultez la Référence API REST pour les comportements HTTP et les portées. Pour les connexions d’outils IA, utilisez le Guide MCP.

​Configurer un client

​Jetons d’accès OAuth

​Délais et annulation

​Répétition des requêtes

​Traiter les erreurs

​Dépannage

Configurer un client

Jetons d’accès OAuth

Délais et annulation

Répétition des requêtes

Traiter les erreurs

Dépannage