> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Lista de erros do SILOC
> Consulte os códigos de erro do SILOC, o status HTTP que cada um carrega, e a ação que o resolve.
**Formato do erro**
O SILOC retorna erros como problem details RFC 9457, com o media type `application/problem+json`:
```json JSON theme={null}
{
"type": "https://errors.lerian.studio/v1/SILOC-0007",
"title": "Not Found",
"status": 404,
"detail": "participant not found",
"code": "SILOC-0007"
}
```
**Definições de campos**
* **`type`** – Uma URI que identifica o erro no catálogo de erros da Lerian, construída como `https://errors.lerian.studio/v1/`. Esta URI repete `code`, então ela não separa dois status que compartilham um código. Uma requisição que falha na validação de schema traz o padrão do RFC `about:blank` em vez disso.
* **`title`** – O texto do status HTTP (por exemplo, `Not Found`).
* **`status`** – O código de status HTTP.
* **`detail`** – Uma explicação legível por humanos desta ocorrência. Uma resposta `500` substitui o texto por `internal error`, para que a causa interna permaneça dentro do trilho. O texto varia por ocorrência, e um `403` pode trazer a mensagem que o serviço de autorização reportou. Não baseie sua lógica nele.
* **`code`** – O código estável e legível por máquina (`SILOC-NNNN`). Baseie sua lógica no par de `status` e `code`, não em `code` isoladamente. Um código pode aparecer sob mais de um status, e cada status precisa de uma ação diferente. O código `SILOC-0002` carrega um 401, um 403 e um 503, cada um com sua própria ação. Uma requisição que falha na validação de schema omite o campo, e `errors` nomeia os campos com falha.
* **`errors`** – Uma lista opcional de detalhes em nível de campo, cada um com o `location` que leu, um `message` e o `value` encontrado ali.
As tabelas abaixo listam os códigos que o SILOC retorna, agrupados por status HTTP.
## 401: Chamador não identificado
***
| `code` | Descrição | `detail` |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| SILOC-0002 | A requisição chegou sem um bearer token, ou com um token cujas claims não identificam um principal. | `Missing Token`, ou `Unauthorized` |
| SILOC-0003 | Uma requisição que altera estado chegou ao gate de idempotência sem um chamador identificado para atribuir o `Idempotency-Key`. | `authenticated principal unavailable` |
## 403: Chamador recusado
***
| `code` | Descrição | `detail` |
| ---------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| SILOC-0002 | O serviço de autorização recusou este chamador para o recurso e a ação que a requisição direciona. | `Forbidden`, ou a mensagem que o serviço de autorização reportou |
## 404: Não encontrado
***
| `code` | Descrição | `detail` |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SILOC-0007 | O path ou a query nomeou um recurso que o trilho não possui. Verifique o identificador, ou liste a coleção para encontrar um válido. | `participant not found`, `certificate not found`, `relay failure not found`, `cycle not found`, `settlement instruction not found`, `cycle reconciliation not found`, `business calendar year not covered` |
## 409: Conflitos
***
| `code` | Descrição | `detail` |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SILOC-0009 | A requisição colide com um estado que o trilho já possui, ou com um comando que já consumiu este `Idempotency-Key`. Releia o estado atual antes de repetir a requisição. | `a participant with this ISPB already exists`, `the active credential cannot be disabled; revocation was not recorded`, `notification config was modified concurrently; re-read and retry with the current version`, `a request with this Idempotency-Key is still being processed; retry once it completes`, `the Idempotency-Key was already used with a different request` |
## 422: Erros de validação
***
| `code` | Descrição | `detail` |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SILOC-0022 | A requisição está bem formada, mas viola uma regra de domínio, ou traz um valor que o trilho não consegue interpretar. Corrija o campo que a resposta nomeia e envie a requisição novamente. | `Idempotency-Key header is required on a state-changing request`, `Idempotency-Key must be at most 255 characters`, `invalid pagination cursor`, `participantId must be a valid uuid`, `certificateId must be a valid uuid`, `id must be a valid uuid`, `authorized actor identity is unavailable`, `from/to must be an RFC 3339 date-time`, `malformed semantic ROC payload`, `semantic ROC fiIspb is not the configured local FI`, `no OT cycle correlates the semantic ROC`, `ambiguous OT cycles correlate the semantic ROC`, `semantic ROC revision already ingested with a different content hash`, `semantic ROC revision supersession is invalid` |
## 500: Erros do servidor
***
| `code` | Descrição | `detail` |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| SILOC-0500 | Uma falha inesperada do servidor. O trilho mascara a causa e retorna um texto fixo. Repita a requisição, e cite o identificador de trace da resposta se a falha persistir. | `internal error` |
## 503: Trilho não pode responder
***
| `code` | Descrição | `detail` |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| SILOC-0001 | O trilho não conseguiu chegar a uma decisão sobre este chamador. O serviço de autorização não respondeu, ou o deploy não consegue autorizar com sua configuração atual. | `Service Unavailable` |
| SILOC-0002 | O trilho não conseguiu provar que o comando é único, então o resultado do comando é indeterminado. | O trilho não conseguiu provar que este comando é único, então concilie a requisição original antes de repetir, e nunca repita com uma nova chave |
Um 503 que traz `SILOC-0002` não indica que o comando foi rejeitado. O trilho responde com ele tanto antes de o comando executar quanto depois de ele confirmar, então o comando já pode ter tido efeito. Concilie a requisição original primeiro. Quando você repetir, envie o mesmo `Idempotency-Key`, e nunca repita sob um novo.