---
title: Troubleshooting & FAQ
description: Errori comuni dell'Operator SDK (microfono, WebSocket, token) con i relativi codici, e risposte alle domande frequenti.
---

Questa pagina raccoglie gli errori più comuni con i loro **codici** e le domande
ricorrenti sull'Operator SDK.

## Errori comuni

Gli errori non fatali arrivano sull'evento `error` come `OperatorError`
(`{ code, message, cause? }`). Sottoscrivilo sempre durante lo sviluppo:

```ts
op.on("error", (e) => console.error(e.code, e.message, e.cause));
```

| Codice | Significato | Cosa fare |
|---|---|---|
| `MIC_PERMISSION_DENIED` | Il browser o il sistema operativo ha negato l'accesso al microfono. | Verifica i permessi del sito nel browser **e** nelle impostazioni del SO. La pagina deve essere su **HTTPS** (o `localhost`). Vedi [Audio & microfono](/docs/operator-sdk/audio-microfono). |
| `WS_ERROR` | Errore sul canale WebSocket (presenza o audio). | Controlla la connettività di rete e che `coreUrl` sia corretto. L'SDK tenta la riconnessione automatica del canale di presenza (backoff configurabile). |
| `UNAUTHORIZED` | Token di sessione non valido in modo persistente (`401`). | Assicurati che `getToken` restituisca sempre un token **fresco**; verifica l'endpoint backend e l'`X-API-Key`. Vedi [Token flow](/docs/operator-sdk/token-flow). |
| `REQUEST_FAILED` | Errore di rete o di risposta su una richiesta dell'SDK (es. `listPhoneNumbers`). | Verifica la connettività e che `coreUrl` (`core.audin.ai`) sia raggiungibile dal browser: le richieste dell'SDK usano lo stesso servizio dei WebSocket, non l'endpoint del tuo backend. |

<Callout type="info">
  `UNAUTHORIZED` e `REQUEST_FAILED` sono anche i codici di `OperatorRequestError`
  lanciato da `listPhoneNumbers()` su un fallimento persistente (vedi
  [Numeri & presenza](/docs/operator-sdk/numeri-presenza)).
</Callout>

## Non si sente audio

Se l'operatore o la controparte non si sentono, segui la procedura di diagnosi
passo-passo nella pagina [Audio & microfono](/docs/operator-sdk/audio-microfono):
permessi microfono (OS + browser), device corretto via `setAudioConstraints`,
stato di `mute`, contesto sicuro (HTTPS) e gesto utente per sbloccare l'audio.

## Il token scade / errore 401

Il token di sessione vive **circa un'ora**. L'SDK richiama `getToken` ogni volta
che serve un token nuovo — alla connessione, a ogni riconnessione e all'apertura
del canale audio di una chiamata. Se vedi errori `401` / `UNAUTHORIZED`:

- Assicurati che la tua callback `getToken` **recuperi sempre un token fresco** e
  non restituisca un token scaduto messo in cache.
- Verifica che il tuo endpoint backend autentichi correttamente con l'header
  `X-API-Key` verso `https://api.audin.ai/operator-sessions/token`.

Dettagli completi nella pagina [Token flow & setup backend](/docs/operator-sdk/token-flow).

## FAQ

<Accordions>
<Accordion title="Un operatore può gestire più chiamate contemporaneamente?">
No. In questa versione (MVP) vale **una sola chiamata attiva per operatore**.
Mentre una chiamata è in corso, le offerte in entrata vengono **rifiutate
automaticamente** (non ricevi un `incomingCall`) e `dial()` **fallisce**. Il
supporto multi-linea potrà essere aggiunto in futuro senza cambiare l'API
pubblica.
</Accordion>

<Accordion title="Posso usare lo stesso numero con operatori dashboard e operatori esterni dell'SDK?">
No. Un numero gestito dagli operatori esterni dell'SDK serve **solo operatori
esterni**: non si mischia con gli operatori della dashboard sullo stesso numero.
</Accordion>

<Accordion title="Perché la controparte non sente i toni DTMF?">
I toni **vengono inoltrati alla rete telefonica**: `sendDtmf()` emette la cifra
come messaggio di controllo e il server inietta il tono DTMF in-band sulla
tratta telefonica. Se la controparte non li sente, verifica che il **bridge
audio sia attivo** (la chiamata deve essere stata risposta, stato `active`) e
che il digit sia **valido** (`0`-`9`, `*`, `#`) — in questi casi nessun errore
viene emesso lato SDK: il drop è silenzioso (solo log lato server). Nota:
l'operatore **non** sente comunque il proprio tono — il feedback locale è a
carico della tua UI.
</Accordion>

<Accordion title="L'operatore sente silenzio mentre la chiamata in uscita si connette: è normale?">
Sì. In questa fase **non c'è ringback** (tono di libero): durante la connessione
di una chiamata in uscita l'operatore sente silenzio finché l'audio non è
stabilito (stato `active`). Ti consigliamo di mostrare lo stato `connecting`
nella tua UI per dare un feedback visivo.
</Accordion>

<Accordion title="Devo mettere l'Account API Key nel browser?">
Mai. L'API Key resta **solo sul tuo backend**. Il browser usa esclusivamente un
**token di sessione effimero** ottenuto dalla tua callback `getToken`. Vedi
[Token flow & setup backend](/docs/operator-sdk/token-flow).
</Accordion>

<Accordion title="Quali browser sono supportati?">
Browser moderni con `AudioWorklet`, `getUserMedia` e `WebSocket` (versioni
correnti di Chromium, Firefox e Safari). La pagina deve essere servita su
**HTTPS** (o `localhost`) per l'accesso al microfono; la prima chiamata può
richiedere un gesto dell'utente per sbloccare l'audio.
</Accordion>
</Accordions>

## Vedi anche

<Cards>
  <Card href="/docs/operator-sdk/audio-microfono" title="Audio & microfono" description="Diagnosi audio, permessi e selezione del device." />
  <Card href="/docs/operator-sdk/token-flow" title="Token flow & setup backend" description="Emissione e rinnovo dei token di sessione." />
  <Card href="/docs/operator-sdk/api-reference" title="API reference" description="Eventi, codici di errore e tipi al completo." />
</Cards>