> 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/backend/handling-errors.md). # Tratamento de Erros Um erro significa que uma etapa da integração do backend não pôde ser concluída: a API não pôde responder à solicitação, ou o `signedResponse` não passou na sua validação. Nenhum resultado de liveness é lido. Resultados que informam que o rosto não está vivo, ou que a tentativa não foi concluída, não são erros — veja [Tratamento de falhas](/sdk-lite/sdk-lite-english-pt-br/tratamento-de-falhas/backend/handling-failures.md). ## Erros em resumo | Onde | Erro | Categoria | Pode tentar novamente? | O que fazer | | --------------- | ----------------------------------- | ---------------------- | ---------------------- | ----------------------------------------------- | | Resultado | `invalid_params` | Integração | Não | Envie o `attemptId` na URL | | Resultado | `attempt_not_found` | Integração | Não | Verifique o `attemptId` e a região | | Resultado | `images_retrieval_failed` | Servidor | Sim | Tente novamente mais tarde | | Resultado | `internal_server_error` | Servidor | Sim | Tente novamente mais tarde | | Resultado | Token de acesso ausente ou inválido | Autenticação | Sim, com um novo token | Obtenha um novo token de acesso | | Resultado | Token sem o escopo necessário | Authorization | Não | Conceda o escopo e obtenha um novo token | | Token de sessão | Falha na solicitação | Integração ou servidor | Depende de `erro` | Verifique a Mobile Key e o Authentication Token | | Seu backend | Assinatura inválida | Validação | Não | Rejeite o `signedResponse` | | Seu backend | `tokenId` incompatibilidade | Validação | Não | Rejeite o `signedResponse` | ## Erros do endpoint de resultado Erros do `GET /v1/faces/liveness/attempts/{attemptId}/await` use este corpo: ```json { "requestId": "string", "error": "string", "message": "string" } ``` | Campo | Tipo | Descrição | | ----------- | ------ | ----------------------------------------------------------------------------- | | `requestId` | String | Identificador desta solicitação. Inclua-o ao entrar em contato com o suporte. | | `erro` | String | Código de erro padronizado. Veja a tabela abaixo. | | `mensagem` | String | Descrição legível do erro, destinada aos seus logs. | {% hint style="info" %} **Boa prática:** baseie sua lógica em `erro`, nunca em `mensagem`. O `mensagem` é um texto descritivo que pode mudar, então registre-o, mas não o processe. {% endhint %} ### Códigos de erro | `erro` | Quando é retornado | O que fazer | | ------------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `invalid_params` | O `attemptId` está ausente do caminho da solicitação. | Envie o `livenessAttemptId` do verificado `signedResponse` como `{attemptId}` na URL. | | `attempt_not_found` | Não existe tentativa para o `attemptId` enviado. | Verifique se `{attemptId}` corresponde ao `livenessAttemptId` da `signedResponse`, e que você chama a mesma região onde o token de sessão foi emitido. Veja [Regiões](/sdk-lite/sdk-lite-english-pt-br/configuracao/backend/setup.md#regions). | | `images_retrieval_failed` | As imagens associadas à tentativa (a imagem principal ou os quadros extras) não puderam ser recuperadas. | Tente a chamada novamente mais tarde. Se persistir, entre em contato com o suporte com o `requestId`. | | `internal_server_error` | Um erro inesperado não coberto pelos outros códigos. | Tente a chamada novamente mais tarde. Se persistir, entre em contato com o suporte com o `requestId`. | Exemplo: ```json { "requestId": "bb1ce1fd-5d0d-42af-bb0e-16f56b230a20", "error": "attempt_not_found", "message": "Tentativa não encontrada para o id 01K1XDD6W98M5QM9B8EAZZDV49" } ``` ### Erros de autenticação e autorização Esses erros ocorrem antes de a tentativa ser lida, e não carregam um `erro` código. O corpo deles pode diferir do formato acima. | Situação | O que fazer | | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | O `Authorization` o cabeçalho está ausente, ou o token de acesso é inválido ou expirado. | Obtenha um novo token de acesso ([Configuração — etapa 4](/sdk-lite/sdk-lite-english-pt-br/configuracao/backend/setup.md)) e tente novamente. | | O token de acesso é válido, mas a aplicação Connect não tem `v1-faces-liveness-attempts:read`. | Conceda o escopo à aplicação no Trust, obtenha um novo token de acesso e tente novamente. | {% hint style="warning" %} Verifique se você está usando as **Aplicativo Connect** credenciais para obter o token de acesso. A Mobile Key `client-secret` é usada apenas para o token de sessão e para verificar o `signedResponse`. {% endhint %} ### Timeouts e erros de servidor O endpoint de resultado aguarda no servidor enquanto a tentativa é processada. Se o seu cliente HTTP esgotar o tempo limite, verifique se o timeout dele está acima de **15 segundos**, então chame o mesmo endpoint novamente: a chamada retorna o mesmo resultado para o mesmo `attemptId`. Para erros inesperados do servidor, tente novamente mais tarde com um número limitado de tentativas. Se o erro persistir, entre em contato com o suporte com o `requestId`. ## Erros do token de sessão Quando a solicitação do token de sessão falha, o corpo da resposta contém apenas um `erro` campo com o motivo da falha: ```json { "error": "string" } ``` Verifique a Mobile Key e o Authentication Token descritos em [Autenticação](https://docs.caf.io/caf-sdk/authentication), e que ambos pertencem à região que você está chamando. Sem um token de sessão, o app não pode iniciar o SDK. ## Erros de validação Esses erros são gerados pelo seu próprio backend ao validar o `signedResponse` ([Configuração — etapa 3](/sdk-lite/sdk-lite-english-pt-br/configuracao/backend/setup.md)). Em ambos os casos, **rejeite o `signedResponse`** e não chame o endpoint de resultado. | Verifique | Falha quando | O que isso pode indicar | O que fazer | | ---------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | Assinatura | O JWT não pode ser verificado com a sua Mobile Key `client-secret`. | A resposta foi modificada, ou não foi emitida para a sua conta. Também pode ser um problema de configuração, como uma Mobile Key de outra região ou conta. | Rejeite-a. Confirme a Mobile Key; se estiver correta, trate a resposta como não confiável. | | `tokenId` | O `tokenId` no payload não corresponde ao `tokenId` armazenado para esta sessão. | A resposta pertence a outra sessão, ou está sendo reenviada. | Rejeite-a e inicie uma nova tentativa com um novo token de sessão. | {% hint style="warning" %} Nunca pule essas verificações, nem mesmo em ambientes de teste. Elas garantem que o resultado lido pelo seu backend pertença à sessão que ele criou. {% endhint %} ## Entrando em contato com o suporte Ao entrar em contato com o suporte sobre um erro de backend, inclua: * O `requestId` da resposta com falha. * O `livenessAttemptId` (ou `attemptId`) e o `sessionId`, quando disponível. * A região que você chamou (EUA ou Brasil). * O `erro` código e o `mensagem`. Não envie tokens de acesso, segredos de cliente ou as imagens capturadas. --- # 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/backend/handling-errors.md?ask=&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.