> For the complete documentation index, see [llms.txt](https://docs.skail.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.skail.dev/construir/sdk-.net/excecoes.md). # Exceções As exceções que o SDK pode lançar no seu código, quando acontecem e o que fazer com cada uma. Mais o mapeamento entre os códigos HTTP do skail e os `StatusCode` que aparecem em `SkailException`. ## Exceções do SDK | Exceção | Quando acontece | O que fazer | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SkailNonDeterministicException` | O replay divergiu do histórico da execução: o passo que o código quer executar não é o que foi registrado naquela posição (índice diferente, ou tipo de evento e endereço do método diferentes) | Corrigir o código. Nunca capturar. Causas: relógio, aleatoriedade ou I/O na function; `Task.Delay`/`Task.WhenAll` na function; fluxo alterado com execuções em andamento; método renomeado. Ver [Determinismo e replay](/aprender/fundamentos/determinismo-e-replay.md) e [Versionamento](/aprender/fundamentos/versionamento-de-codigo-com-execucoes-em-andamento.md) | | `SkailException` | Erro na comunicação com o skail (buscar trabalho, gravar um passo, confirmar). Carrega `StatusCode` com o código gRPC mapeado da resposta HTTP do skail | O runtime já retenta os códigos transitórios (`DeadlineExceeded`, `Aborted`, `Unavailable`) antes de lançar. Se chegar ao seu código, em geral é configuração (`Unauthenticated`, `PermissionDenied`, `NotFound`) ou limite (`ResourceExhausted`). Não capture para seguir em frente; corrija a causa | | `SkailCanceledException` | A execução foi cancelada (`StatusCode.Cancelled`) | Deixe propagar | | `SkailEventStoreException` | Falha ao registrar um passo da execução no skail | Interna; o runtime trata. Se aparecer no seu log de forma recorrente, é sintoma de indisponibilidade; ver [Troubleshooting](/operar/troubleshooting.md) | Exceções lançadas pelo seu próprio código dentro de um command seguem a regra de retry: retentadas até `retryCount`, depois lançadas dentro da function. Ver [Falhas, retries e idempotência](/aprender/fundamentos/falhas-retries-e-idempotencia.md). ## Mapeamento HTTP → StatusCode Quando o skail responde ao runtime com um erro HTTP, a `SkailException` carrega o `StatusCode` gRPC correspondente: | HTTP | `StatusCode` | Retentado pelo runtime | | -------- | ------------------- | ---------------------- | | 400 | `InvalidArgument` | Não | | 401 | `Unauthenticated` | Não | | 403 | `PermissionDenied` | Não | | 404 | `NotFound` | Não | | 409 | `Aborted` | Sim | | 429 | `ResourceExhausted` | Não | | 500 | `Internal` | Não | | 502, 503 | `Unavailable` | Sim | | 504 | `DeadlineExceeded` | Sim | A mensagem da exceção é extraída do corpo JSON da resposta do skail (campos `message`, `detail`, `title`, `error`, na ordem em que existirem). ## Mensagens de erro do runtime Não são exceções tipadas do SDK, mas aparecem no log e têm causa conhecida: | Mensagem | Causa | Correção | | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | "There is not Skail runtime available!" | Método skail chamado sem `builder.UseSkail()`/`services.AddSkail()`; ou o pacote de build não rodou (IL weaving); ou teste sem a plataforma de testes | Confira `UseSkail`, o pacote `Skail.Platform.Runtime.Build` no build e `[assembly: VisibleToSkailPlatform]` | | "The Builder Factory can only be registered once!" | `AddSkail`/`UseSkail` chamado mais de uma vez no mesmo processo (dois `ServiceProvider`) | Uma só registração por processo; em testes, isole | | "StateMachine not registered." | Método decorado não descoberto: assembly sem o atributo, método não `async`, assinatura errada, `AddSkail` antes do assembly carregar | Confira atributo, `async`, retorno `SkailTask` | | "Target method not found" | O endereço da execução não corresponde a nenhuma function publicada: `SKAIL_WORKLOAD` diferente do que gerou a execução, método renomeado, `skailMethodName` alterado | Confira `SKAIL_WORKLOAD` e nomes | | "Message image mismatch" | Execução endereçada a outro workload entregue a este processo | Confira `SKAIL_WORKLOAD` | | "Hibernation is not allowed in the unit test." | Um teste unitário alcançou `Delay`/`WaitForEvent` não satisfeito | Teste até o ponto de espera; ver [Como testar](/construir/testar-depurar-e-observar/como-testar-funcoes-com-skail.platform.runtime.testing.md) | ## O que capturar e o que não Capture, na function, as exceções dos seus próprios commands depois que esgotaram o retry, para compensar ou decidir. Não capture `SkailNonDeterministicException` nem `SkailException` de forma genérica; use `catch (Exception ex) when (ex is not SkailNonDeterministicException)` se precisar de um catch amplo. Ver [Como tratar erros e compensar](/construir/escrever-fluxos/como-tratar-erros-e-compensar.md). ## Veja também [Troubleshooting](/operar/troubleshooting.md), [Falhas, retries e idempotência](/aprender/fundamentos/falhas-retries-e-idempotencia.md), [Regras do analyzer](/construir/sdk-.net/regras-do-analyzer-skail001-skail002-skail003.md).