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

# Configuration et erreurs

> Authentification, accès à l’espace de travail, domaines, contrôle des requêtes et dépannage

## Configurer un client

```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 | 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 :

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

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](/fr/api-reference/introduction).

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](/fr/sdk/usage#adapter-une-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.

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

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.

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

## Traiter les erreurs

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

| 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](/fr/web-widget). |

Vérifiez indépendamment les mêmes identifiants avec la [CLI](/fr/cli/overview) :

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

Consultez la [Référence API REST](/fr/api-reference/introduction) pour les comportements HTTP et les portées. Pour les connexions d’outils IA, utilisez le [Guide MCP](/fr/mcp/overview).


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