# Troubleshooting [#troubleshooting]

> Pergunta: "qual ação tomar para cada erro ou falha de conexão?"

| Sinal                         | Significado                              | Ação do integrador                                                                |
| ----------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------- |
| `browser_unavailable`         | Não há ambiente browser.                 | Mova a criação/início para o cliente; não execute em SSR/Node.                    |
| `secure_context_required`     | A página não é segura.                   | Use HTTPS; `localhost` serve apenas no desenvolvimento.                           |
| `microphone_unavailable`      | O browser não expõe `getUserMedia`.      | Use um browser suportado e confirme a política/integração de mídia.               |
| `microphone_access_failed`    | Captura foi recusada ou falhou.          | Solicite permissão por uma ação do usuário e trate a recusa sem tentar ocultá-la. |
| `transport_connection_failed` | A sessão não confirmou o socket inicial. | Confira endpoint, rede e configuração do provider.                                |
| `transport_disconnected`      | Transporte caiu após iniciar.            | Observe `disconnected.willRetry`, `reconnecting` e `reconnected`.                 |
| `session_start_failed`        | Outra falha impediu o início.            | Mostre uma falha recuperável ao usuário e registre somente metadados seguros.     |
| `all_candidates_failed`       | Todos os candidatos foram tentados.      | Inspecione a ordem de `attempts`; não exponha causas contendo dados sensíveis.    |

Erros de ambiente não aparecem em `attempts`: eles interrompem fallback antes de qualquer
tentativa. Isso evita diagnosticar uma página sem HTTPS ou sem microfone como falha de todos
os endpoints descobertos.

Para batch, `BatchReprocessError` cobre disponibilidade/estado do áudio e falhas de upload.
Não tente interpretar o corpo de uma resposta não-2xx: ele é opaco por contrato atual. Veja
[batch-e-reprocessamento.md](/pt/docs/transcription/latest/markdown/batch-e-reprocessamento) para as limitações do endpoint.

Se o erro só ocorre contra o provider, não conclua que há smoke de referência disponível:
o smoke real-provider ainda depende de credencial e ambiente fornecidos pelo integrador.