SILOC error list

Error format SILOC returns errors as RFC 9457 problem details with the application/problem+json media type:

{
  "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/<code>. 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.

Integration

Connectivity

Participants

Cycles and settlement

Alerts and audit

Schedule

Error handling

SILOC error list

401: Unidentified caller

403: Refused caller

404: Not found

409: Conflicts

422: Validation errors

500: Server errors

503: Rail cannot answer

​401: Unidentified caller

​403: Refused caller

​404: Not found

​409: Conflicts

​422: Validation errors

​500: Server errors

​503: Rail cannot answer

401: Unidentified caller

403: Refused caller

404: Not found

409: Conflicts

422: Validation errors

500: Server errors

503: Rail cannot answer