> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/tratamento-de-erros/ios/error-handling.md).

# Tratamento de erros

Quando não é possível concluir o processo de prova de vida, o SDK chama `didFinishWithError(type:description:)` no seu `CafFaceLivenessLiteDelegate`. O parâmetro `type` é um valor de `CafErrorType` que informa por que o processo foi interrompido.

Esta página explica o que cada resultado significa, quando se espera que cada erro ocorra e como orientar o usuário na próxima tentativa.

## Resumo dos resultados

Cada execução de prova de vida termina com exatamente um dos quatro callbacks do delegate abaixo. Trate-os e informe-os separadamente: eles têm causas e próximos passos diferentes.

| Resultado     | Callback                                                 | O que significa                                                                                    | `signedResponse` | Próximo passo para o usuário                                                                                    |
| ------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------- |
| **Sucesso**   | `didFinishWithSuccess(livenessResult:)`                  | A captura foi concluída.                                                                           | Sim              | Continue o fluxo. Seu backend recupera o resultado final da prova de vida usando `signedResponse`.              |
| **Falha**     | `didFinishWithFailure(type:description:signedResponse:)` | A captura foi realizada e avaliada, mas não foi aprovada. Isso não é um julgamento sobre a pessoa. | Sim              | Oriente o usuário com base na falha `type` e ofereça uma nova tentativa.                                        |
| **Erro**      | `didFinishWithError(type:description:)`                  | O processo não pôde ser iniciado ou concluído. Nenhuma captura foi avaliada.                       | Não              | Depende do erro `type`. Consulte [Resumo dos tipos de erro](#error-types-at-a-glance).                          |
| **Cancelado** | `cancelled()`                                            | O usuário fechou a tela de captura ou colocou o app em segundo plano durante a captura.            | Não              | Volte à tela anterior sem exibir uma mensagem de erro. Deixe o usuário iniciar novamente quando estiver pronto. |

{% hint style="warning" %}
Nunca determine o resultado da prova de vida no cliente. Seu backend valida a `signedResponse` (assinatura e `tokenId`) e, em seguida, recupera o resultado final usando o `livenessAttemptId` que ela contém. Consulte [Configuração do backend](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/configuracao/backend/setup.md).
{% endhint %}

### Falhas servem para orientar, não para diagnosticar

Cada tentativa é avaliada individualmente. Duas tentativas da mesma pessoa com um minuto de intervalo são dois conjuntos distintos de evidências. Por isso, um usuário legítimo pode falhar em uma tentativa e passar na seguinte, mesmo em condições aparentemente iguais. Isso significa que o sistema está funcionando conforme o esperado.

O `type` da falha responde à pergunta *"o que tem mais chance de ajudar este usuário a passar na próxima tentativa?"*, e não *"qual era o problema com esta imagem?"*. Lembre-se de que:

* Um código de falha pode ser retornado mesmo quando a imagem capturada parece nítida e bem iluminada. A decisão considera toda a captura, não apenas o quadro final.
* As orientações são intencionalmente genéricas. Mensagens consistentes que não revelam detalhes ajudam usuários legítimos sem dizer a um invasor o que mudar.
* `motionIssue` e `deviceIssue` podem ser orientações genéricas e não refletir a causa real. Muitas vezes, o problema é resolvido na próxima tentativa, no mesmo dispositivo. Peça ao usuário que alinhe o rosto dentro do oval, fique parado e procure uma iluminação melhor. Sugira outro dispositivo apenas como alternativa, após várias tentativas.

Os tipos de falha e a mensagem recomendada para cada um estão em [Motivos de falha e orientações ao usuário](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/tratamento-de-falhas/mobile/failure-handling.md).

## O callback de erro

```swift
public protocol CafFaceLivenessLiteDelegate: AnyObject {
    // ...
    func didFinishWithError(type: CafErrorType, description: String)
}
```

| Parâmetro     | Descrição                                                                                                                                                                                                                                   |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`        | O `CafErrorType` que indica por que o processo foi interrompido                                                                                                                                                                             |
| `description` | Descrição técnica do erro, destinada aos logs. Nunca a exiba ao usuário. Ela pode começar com uma breve descrição no idioma do dispositivo, seguida do detalhe técnico, por exemplo `<label>. invalid_token`. Use o detalhe para investigar |

Um erro sempre encerra a execução da verificação de prova de vida, e nenhum `signedResponse` é retornado. Você pode chamar `startSDK(viewController:)` novamente logo após receber o erro, com a configuração já passada para `setup`.

Chamar `startSDK` enquanto uma captura ainda está em andamento não gera um erro: a chamada é ignorada e nenhum método do delegate é chamado. Aguarde a execução atual terminar com um dos callbacks acima antes de iniciar outra.

## Uso do `type` como parâmetro

{% hint style="info" %}
**Boa prática:** não exiba aos usuários finais o nome do enum sem tratamento nem o conteúdo de `description` . Associe o `type` a uma mensagem localizada no seu app e registre o conteúdo de `description` nos logs para que sua equipe possa investigar. O conteúdo de `description` é um texto técnico que pode mudar entre versões, portanto não o analise nem crie lógica com base nele.
{% endhint %}

{% hint style="info" %}
Alguns tipos de erro têm uma **Descrições conhecidas** tabela que lista os detalhes técnicos mais comuns encontrados em `description` e o que cada um significa. Use estas tabelas para agrupar erros nos seus logs, painéis e chamados de suporte. Seu app ainda deve decidir o que exibir e se deve tentar novamente com base apenas no `type`.
{% endhint %}

Alguns erros podem ser resolvidos pelo usuário, por exemplo, concedendo permissão para a câmera ou reconectando-se à internet. Outros apontam para um problema de integração, como iniciar antes de `setup`, e precisam ser corrigidos no seu app ou na configuração da conta.

{% hint style="warning" %}
Nunca informe ao usuário qual verificação de segurança falhou nem exiba detalhes técnicos, como dados de certificados, endereços internos ou rastreamentos de pilha. Essas informações ajudam quem está tentando burlar o fluxo.
{% endhint %}

## Tipos de erro em resumo

| Tipo                            | Categoria                | O usuário pode tentar novamente?     | Mensagem recomendada                                                 |
| ------------------------------- | ------------------------ | ------------------------------------ | -------------------------------------------------------------------- |
| `invalidOptionsException`       | Integração               | Não                                  | Não foi possível concluir a verificação.                             |
| `tokenException`                | Integração               | Sim, com um novo token               | Não foi possível concluir a verificação. Tente novamente.            |
| `invalidResponseException`      | Integração               | Sim                                  | Não foi possível concluir a verificação. Tente novamente.            |
| `cameraPermission`              | Usuário e ambiente       | Sim, após conceder acesso            | Permita o acesso à câmera para continuar.                            |
| `networkException`              | Usuário e ambiente       | Sim                                  | Sem conexão. Verifique sua internet e tente novamente.               |
| `serverException`               | Usuário e ambiente       | Sim                                  | Não foi possível concluir a verificação. Tente novamente.            |
| `userTimeoutException`          | Usuário e ambiente       | Sim                                  | Não foi possível concluir a verificação. Tente novamente.            |
| `captureAlreadyActiveException` | Usuário e ambiente       | Sim, após o término da captura atual | Você já tem uma verificação em andamento. Feche-a e tente novamente. |
| `unsupportedDevice`             | Usuário e ambiente       | Não                                  | Não foi possível concluir a verificação.                             |
| `securityException`             | Segurança do dispositivo | Sim                                  | Não foi possível concluir a verificação. Tente novamente.            |
| `unexpectedErrorException`      | Outro                    | Sim                                  | Não foi possível concluir a verificação. Tente novamente.            |

## Erros de integração

Esses erros geralmente apontam para um problema na integração entre seu app e o SDK, não para algo que o usuário possa resolver mudando a forma como faz a captura.

### `invalidOptionsException`

O SDK não conseguiu iniciar com a configuração atual. Isso acontece quando:

* `startSDK` foi chamado antes de `setup`.
* O SDK não conseguiu criar o endereço do serviço de captura a partir da configuração da sessão.

**Mensagem recomendada:** *Não foi possível concluir a verificação.*

**Tentar novamente:** não. Corrija a configuração do app.

**O que fazer:** encaminhe o usuário ao suporte ou a outro canal. No seu app, chame `setup(mobileToken:personId:…)` antes `startSDK`. Se `setup` foi chamado e o erro persistir, entre em contato com o suporte da Certta e informe a `description`.

{% hint style="info" %}
Uma nova tentativa não altera o resultado. Esse erro não deve ser frequente em produção; portanto, monitore-o e configure um alerta para quando ele ocorrer.
{% endhint %}

### `tokenException`

O `mobileToken` não está configurado para o fluxo de prova de vida. Isso acontece quando:

* A conta associada ao token não está habilitada para o fluxo assíncrono do Face Liveness Lite.
* A sessão foi criada sem os dados necessários para iniciar a captura ou sem a `signedResponse`.

**Mensagem recomendada:** *Não foi possível concluir a verificação. Tente novamente.*

**Tentar novamente:** sim, com um novo token.

**O que fazer:** ofereça uma nova tentativa com um novo token. Se o erro persistir com tokens novos, verifique a configuração do token com a equipe responsável pela sua conta Certta.

{% hint style="info" %}
Um token expirado ou inválido não é informado como `tokenException`. Ele é informado como `serverException`. Consulte [`serverException`](#serverexception).
{% endhint %}

### `invalidResponseException`

A sessão foi criada sem o identificador da tentativa de prova de vida, por isso não foi possível registrar a captura. O SDK é interrompido antes de iniciar a captura do usuário.

**Mensagem recomendada:** *Não foi possível concluir a verificação. Tente novamente.*

**Tentar novamente:** sim. Se continuar acontecendo, entre em contato com o suporte da Certta e informe a `description`.

## Erros do usuário e do ambiente

Esses erros dependem do usuário, do dispositivo ou da rede. Exiba uma mensagem útil e permita que o usuário tente novamente quando fizer sentido.

### `cameraPermission`

O usuário negou o acesso à câmera. `startSDK` verifica a permissão antes de qualquer solicitação de rede e exibe a solicitação do sistema caso o usuário ainda não tenha decidido. Esse erro também pode ser informado durante a captura. Causas comuns:

* O usuário negou o acesso quando a permissão foi solicitada.
* A permissão já havia sido negada. O sistema não pergunta novamente.
* A permissão foi revogada nos Ajustes ou bloqueada por restrições do dispositivo, como Tempo de Uso, controles parentais ou gerenciamento corporativo do dispositivo.

**Mensagem recomendada:** *Permita o acesso à câmera para continuar.*

**Tentar novamente:** sim, depois que o usuário conceder a permissão.

**O que fazer:** exiba uma tela específica com um botão que abra os ajustes do app e, em seguida, chame `startSDK` novamente.

{% hint style="info" %}
Como o sistema não exibe a solicitação de permissão novamente, o botão deve abrir diretamente os ajustes do app, em vez de apenas tentar de novo.
{% endhint %}

### `networkException`

A conexão caiu **durante a captura**.

**Mensagem recomendada:** *Sem conexão. Verifique sua internet e tente novamente.*

**Tentar novamente:** sim.

**O que fazer:** exiba uma tela de conexão com um botão para tentar novamente.

{% hint style="info" %}
`networkException` abrange apenas a captura em si. Problemas de conexão enquanto o SDK ainda está criando a sessão, antes de a câmera abrir, são relatados como `serverException`.
{% endhint %}

#### Descrições conhecidas

Todos os detalhes abaixo indicam uma conexão instável durante a captura. Geralmente, uma nova tentativa resolve o problema.

| Detalhe em `description`                                                                            | O que significa                                                                                                        |
| --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `WebSocketError`                                                                                    | A conexão com o serviço de captura caiu durante a captura.                                                             |
| `Socket timeout`                                                                                    | A conexão parou de responder durante a captura.                                                                        |
| `NWError`, seguido de uma mensagem do sistema, como `Network is down` ou `Connection reset by peer` | O iOS informou um erro de rede durante a captura, por exemplo, porque o dispositivo perdeu a conexão ou mudou de rede. |
| `BinaryDecodingError`                                                                               | Os dados recebidos do serviço de captura estavam incompletos, geralmente por causa de uma conexão instável.            |

### `serverException`

O serviço de verificação de vivacidade não conseguiu concluir a solicitação. Isso acontece quando:

* Não foi possível criar a sessão: não há conexão quando o SDK é iniciado, ocorre um tempo limite ou a resposta é inválida ou ilegível. Nesse caso, a tela de captura não é aberta.
* O `mobileToken` expirou, foi reutilizado de uma sessão anterior, é inválido ou pertence a outro ambiente.
* A sessão aponta para uma configuração de captura não compatível com este SDK.
* O serviço informou um erro durante a captura.
* A sessão de captura não era mais válida quando a captura foi iniciada.

**Mensagem recomendada:** *Não foi possível concluir a verificação. Tente novamente.*

**Tentar novamente:** sim, com um novo token. Se o problema continuar acontecendo, entre em contato com o suporte da Certta.

{% hint style="info" %}
Crie o token imediatamente antes de abrir o SDK e gere um novo para cada tentativa.
{% endhint %}

#### Descrições conhecidas

| Detalhe em `description`                                                    | O que significa                                                                                                                                                                                                             | O que fazer                                                                                                                                                              |
| --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `invalid_token`                                                             | O serviço de captura não aceitou a sessão de captura quando a captura foi iniciada, antes de a câmera se conectar. Esse é um caso temporário conhecido, geralmente relacionado a uma conexão instável no início da captura. | Ofereça uma nova tentativa com um novo token. Geralmente, o problema é resolvido na tentativa seguinte.                                                                  |
| `network_timeout`                                                           | O serviço de captura não respondeu a tempo.                                                                                                                                                                                 | Trate isso como um problema de conexão: verifique a conexão e ofereça uma nova tentativa.                                                                                |
| `unexpected_exception`                                                      | O serviço de captura teve uma falha momentânea.                                                                                                                                                                             | Ofereça uma nova tentativa. Se o problema continuar acontecendo, entre em contato com o suporte da Certta.                                                               |
| `invalidResponse`                                                           | Não foi possível ler a resposta à solicitação da sessão, geralmente porque a conexão caiu enquanto a sessão estava sendo criada.                                                                                            | Verifique a conexão e ofereça uma nova tentativa.                                                                                                                        |
| Uma página HTML ou uma mensagem informando que o acesso não está autorizado | A infraestrutura do serviço recusou a solicitação da sessão antes da captura, por exemplo, devido a um bloqueio de rede ou a um token de outro ambiente.                                                                    | Ofereça uma nova tentativa com um novo token. Se o problema continuar acontecendo, entre em contato com o suporte da Certta e informe a data e a hora de cada tentativa. |

{% hint style="warning" %}
A descrição técnica desse erro pode conter mensagens de autorização da infraestrutura do serviço, detalhes de certificados, endereços internos ou rastreamentos de pilha. Nunca a mostre ao usuário nem a envie para logs ou ferramentas que possam ser lidos por pessoas de fora da sua equipe.
{% endhint %}

### `userTimeoutException`

A sessão de captura atingiu o limite de tempo antes que a captura pudesse ser concluída.

{% hint style="info" %}
Quando o usuário abre a captura e não posiciona o rosto antes que o tempo acabe, o SDK retorna a `processingFault` falha em vez deste erro. Se o app for para segundo plano durante a captura (uma chamada recebida, troca de app ou bloqueio da tela), o SDK chama `cancelled()`. Consulte [Falha no processamento](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/tratamento-de-falhas/mobile/failure-handling.md#processing-failure).
{% endhint %}

**Mensagem recomendada:** *Não foi possível concluir a verificação. Tente novamente.*

**Tentar novamente:** sim.

**O que fazer:** mostre orientações breves sobre a captura antes da nova tentativa. Consulte [Como ajudar os usuários a serem aprovados na primeira tentativa](#helping-users-pass-on-the-first-attempt).

### `captureAlreadyActiveException`

Outra captura já estava em andamento quando esta tentou iniciar, por exemplo, após dois toques seguidos no botão de início ou ao reabrir a tela de verificação antes de a captura anterior ser encerrada.

**Mensagem recomendada:** *Você já tem uma verificação em andamento. Feche-a e tente novamente.*

**Tentar novamente:** sim, depois que a captura atual terminar.

**O que fazer:** aguarde a captura em andamento terminar antes de iniciar outra. Desative o botão de início após o primeiro toque: em alguns casos, uma segunda solicitação de início é simplesmente ignorada, sem retorno de chamada.

### `unsupportedDevice`

O dispositivo não pode executar a captura. Causas comuns:

* Um dispositivo ou uma versão do iOS antigos que não atendam aos requisitos da captura.
* Recursos de hardware necessários para a captura ausentes, como uma câmera frontal funcional.
* Não foi possível abrir a câmera ou ela falhou durante a captura, por exemplo, porque está indisponível ou bloqueada pelas restrições do dispositivo.
* Um erro do Keychain: o SDK não conseguiu armazenar com segurança as credenciais da sessão no dispositivo, por exemplo, porque o Keychain não estava disponível naquele momento.

**Mensagem recomendada:** *Não foi possível concluir a verificação.*

**Tentar novamente:** não. Uma nova tentativa no mesmo dispositivo geralmente retorna o mesmo erro.

**O que fazer:** encaminhe o usuário para outro dispositivo ou outro fluxo de verificação. Consulte [Requisitos](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/configuracao/ios/configuration.md#requirements).

{% hint style="info" %}
Registre a `description`, o modelo do dispositivo e a versão do iOS. Se o erro ocorrer em dispositivos que atendem aos requisitos, compartilhe esses detalhes com o suporte da Certta para que o caso possa ser analisado.
{% endhint %}

## Erros de segurança do dispositivo

### `securityException`

`enableSecurity` está `true` e o SDK identificou um risco no dispositivo ou no ambiente do app, antes ou durante a captura. Consulte [Verificações de segurança](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/configuracao/ios/security-checks.md).

**Mensagem recomendada:** *Não foi possível concluir a verificação. Tente novamente.*

**Tentar novamente:** sim. Se o problema persistir, encaminhe o usuário para outro fluxo de verificação.

**O que fazer:** mostre uma mensagem genérica. As verificações são executadas novamente a cada `startSDK`; portanto, o mesmo ambiente retorna o mesmo erro até que a condição deixe de ocorrer.

{% hint style="warning" %}
Nunca informe ao usuário qual verificação falhou, pois isso ensina como contornar a proteção. Se o volume de ocorrências entre usuários legítimos for relevante, analise os logs junto com a Certta.
{% endhint %}

## Outros erros

### `unexpectedErrorException`

Ocorreu um erro inesperado durante a captura.

**Mensagem recomendada:** *Não foi possível concluir a verificação. Tente novamente.*

**Tentar novamente:** sim.

**O que fazer:** registre o tipo, a `description`, a versão do SDK (`CafFaceLivenessLiteSDK.getVersion()`), o modelo do dispositivo e a versão do iOS, e compartilhe essas informações com o suporte da Certta se o problema continuar acontecendo.

{% hint style="info" %}
`CafErrorType` é compartilhado com outros SDKs da Certta e declara mais casos do que o CafFaceLivenessLite retorna. Ao usar `switch` para percorrê-lo, adicione um caso `default` em vez de tratar todos os casos. Consulte [Referência de resultados](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/configuracao/ios/result-reference.md).
{% endhint %}

## Verificações de segurança do dispositivo

Quando `enableSecurity` é `true` (o padrão), o SDK verifica a integridade do dispositivo e do ambiente do app antes e durante a captura e informa `securityException` ao identificar um risco. A própria decisão de vivacidade também executa verificações contra ataques no servidor, que chegam ao seu app como uma falha com um `signedResponse`.

Consulte [Verificações de segurança](https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/configuracao/ios/security-checks.md) para saber como as duas camadas funcionam, ver a matriz de configuração e testar sua integração.

## Novas tentativas e investigação

### Permitir novas tentativas

* Permita pelo menos **duas** tentativas. Três é a prática recomendada.
* Acompanhe a **conclusão em até três tentativas por usuário** junto com a taxa de aprovação na primeira tentativa. À medida que sua base de usuários cresce, espere que alguns usuários legítimos precisem de mais de uma tentativa.

### Ajudar usuários a passar na primeira tentativa

Mostre orientações visuais curtas antes da captura. Estas dicas evitam a maioria das falhas:

* Segure o celular na altura dos olhos e alinhe o rosto ao oval.
* Mova a cabeça, não o celular, para alinhar o rosto ao oval.
* Quando o rosto estiver dentro do oval, fique imóvel até o fim da captura.
* Verifique se o rosto está bem iluminado e se não há uma luz forte atrás do usuário.
* Mantenha o rosto inteiro visível, com os olhos abertos.
* Evite fazer a captura dentro de um veículo em movimento.

### Investigar casos

* Analise a conclusão por usuário, não tentativas isoladas.
* Procure padrões por modelo de dispositivo, versão do iOS e versão do SDK. `CafFaceLivenessLiteSDK.getVersion()` retorna a versão do SDK.
* Verifique os tipos de erro e falha retornados em cada tentativa.
* Agrupe os erros por `type` e pelos detalhes em `description`, usando as tabelas de **Descrições conhecidas** desta página. Por exemplo, `serverException` com `invalid_token` e `networkException` com `Socket timeout` ambos apontam para a conexão, não para a integração.
* Compare cada caso com as orientações desta página antes de encaminhá-lo para análise.

Ao encaminhar um caso para o suporte da Certta, envie, para **cada tentativa** do usuário:

* Data e hora da tentativa.
* Para erros: o `type` e a `description`.
* Para falhas: o `type` e o `signedResponse`.

{% hint style="danger" %}
Nunca envie o `mobileToken` nem dados pessoais, como o número do documento do usuário ou imagens do rosto, em chamados de suporte ou registros.
{% endhint %}

## Exemplo de implementação

Veja um exemplo de como você pode tratar `didFinishWithError` no seu delegado:

```swift
import CafFaceLivenessLite

extension YourViewController: CafFaceLivenessLiteDelegate {
    func didFinishWithError(type: CafErrorType, description: String) {
        // 1. Registre os detalhes técnicos para sua equipe (nunca registre o mobileToken ou personId)
        print("Liveness error: type=\(type.rawValue) description=\(description)")

        // 2. Alguns erros não podem ser resolvidos tentando novamente
        switch type {
        case .invalidOptionsException, .unsupportedDevice:
            routeToAlternativeVerification()
            return
        default:
            break
        }

        // 3. Mapeie o 'type' para uma mensagem clara para o usuário
        let userMessage: String
        switch type {
        case .cameraPermission:
            userMessage = "Allow camera access to continue."
        case .networkException:
            userMessage = "No connection. Check your internet and try again."
        case .captureAlreadyActiveException:
            userMessage = "You already have a verification in progress. Close it and try again."
        default:
            userMessage = "We couldn't complete the verification. Please try again."
        }

        // 4. Exiba a mensagem na sua interface
        showErrorDialog(userMessage)
    }

    // didFinishWithSuccess, didFinishWithFailure, cancelled, loading e loaded
    // são abordados na página Ciclo de vida do SDK.
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.caf.io/sdk-lite/sdk-lite-english-pt-br/tratamento-de-erros/ios/error-handling.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
