> ## 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.
# SILOC error list
> Look up SILOC error codes, the HTTP status each one carries, and the action that resolves it.
**Error format**
SILOC returns errors as RFC 9457 problem details with the `application/problem+json` media type:
```json JSON theme={null}
{
"type": "https://errors.lerian.studio/v1/SILOC-0007",
"title": "Not Found",
"status": 404,
"detail": "participant not found",
"code": "SILOC-0007"
}
```
**Field definitions**
* **`type`** – A URI that identifies the error in the Lerian error catalog, built as `https://errors.lerian.studio/v1/`. This URI repeats `code`, so it does not separate two statuses that share one code. A request that fails schema validation carries the RFC default `about:blank` instead.
* **`title`** – The HTTP status text (for example, `Not Found`).
* **`status`** – The HTTP status code.
* **`detail`** – A human-readable explanation for this occurrence. A `500` response replaces the text with `internal error`, so the internal cause stays inside the rail. The text varies per occurrence, and a `403` can carry the message the authorization service reported. Do not branch on it.
* **`code`** – The stable, machine-readable code (`SILOC-NNNN`). Dispatch on the pair of `status` and `code`, not on `code` alone. One code can appear under more than one status, and each status needs a different action. The code `SILOC-0002` carries a 401, a 403, and a 503, each with its own action. A request that fails schema validation omits the field, and `errors` names the fields at fault.
* **`errors`** – An optional list of field-level details, each with the `location` it read, a `message`, and the `value` found there.
The tables below list the codes SILOC returns, grouped by HTTP status.
## 401: Unidentified caller
***
| `code` | Description | `detail` |
| ---------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| SILOC-0002 | The request arrived without a bearer token, or with a token whose claims do not identify a principal. | `Missing Token`, or `Unauthorized` |
| SILOC-0003 | A state-changing request reached the idempotency gate without an identified caller to attribute the `Idempotency-Key` to. | `authenticated principal unavailable` |
## 403: Refused caller
***
| `code` | Description | `detail` |
| ---------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| SILOC-0002 | The authorization service refused this caller for the resource and action the request targets. | `Forbidden`, or the message the authorization service reported |
## 404: Not found
***
| `code` | Description | `detail` |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SILOC-0007 | The path or query named a resource the rail does not hold. Verify the identifier, or list the collection to find a valid one. | `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: Conflicts
***
| `code` | Description | `detail` |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SILOC-0009 | The request collides with state the rail already holds, or with a command that already spent this `Idempotency-Key`. Re-read the current state before you retry. | `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: Validation errors
***
| `code` | Description | `detail` |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SILOC-0022 | The request is well formed but breaks a domain rule, or carries a value the rail cannot read. Correct the field the response names and send the request again. | `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: Server errors
***
| `code` | Description | `detail` |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| SILOC-0500 | An unexpected server fault. The rail masks the cause and returns a fixed text. Retry the request, and quote the trace identifier of the response if the fault persists. | `internal error` |
## 503: Rail cannot answer
***
| `code` | Description | `detail` |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| SILOC-0001 | The rail could not reach a decision about this caller. The authorization service did not answer, or the deployment cannot authorize with its current configuration. | `Service Unavailable` |
| SILOC-0002 | The rail could not prove the command unique, so the outcome of the command is undetermined. | The rail could not prove this command unique, so reconcile the original request before you retry, and never retry it with a new key |
A 503 that carries `SILOC-0002` does not tell you the command was rejected. The rail answers with it both before the command runs and after it commits, so the command may already have taken effect. Reconcile the original request first. When you do retry, send the same `Idempotency-Key`, and never retry under a new one.