SILOC error list

Error format SILOC returns errors as RFC 9457 problem details:

{
  "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.
title – The HTTP status text (for example, Not Found).
status – The HTTP status code.
detail – A human-readable explanation for this occurrence. A 500, a SILOC-0023, and a SILOC-0024 replace 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. For example, SILOC-0001 is a 503 from the authorization gate and a 422 from a card operation. A request that fails schema validation carries SILOC-0022, 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. A refusal from the authorization or idempotency gate carries an empty violations list instead.

The tables below list the codes SILOC returns, grouped by HTTP status.

400, 413, 415: Request body refused

Status	`code`	Description	`detail`
400	SILOC-0022	The request body is missing, or it is not valid JSON. Send a JSON body that matches the schema of the operation.	`request body is required`, `validation failed`
413	SILOC-0022	The request body reached the 1 MiB limit. Send a smaller body.	`request body is too large limit=1048576 bytes`
415	SILOC-0022	The request declares a `Content-Type` that is not JSON. Send the body as `application/json`.	`validation failed`

401: Unidentified caller

`code`	Description	`detail`
SILOC-0004	The request arrived without a bearer token, or with a credential the authorization service does not accept.	`Missing Token`, or `Unauthorized`
SILOC-0003	A state-changing request reached the idempotency gate without an identified caller to attribute the `X-Idempotency` to.	`authenticated principal unavailable`
SILOC-0401	A certificate operation reached the rail without a caller identity to record.	`authorized actor identity is unavailable`

403: Refused caller

`code`	Description	`detail`
SILOC-0005	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`, `alert not found`, `relay failure not found`, `quarantined frame not found`, `cycle not found`, `settlement instruction not found`, `cycle reconciliation not found`, `no outbound instruction with that id`, `homologation scenario not found`, `business calendar year not covered`
SILOC-0004	A card operation named a card message or card command the rail does not hold.	`no card message with that id`, `no card command with that id`

409: Conflicts

`code`	Description	`detail`
SILOC-0009	The request collides with state the rail already holds, or with a command that already spent this `X-Idempotency`. 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`, `alert is already inactive`, `notification config was modified concurrently; re-read and retry with the current version`, `a run is already in progress for this scenario; wait for it to finish`, `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.	`validation failed`, `X-Idempotency header is required on a state-changing request`, `X-Idempotency 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`
SILOC-0001	A card operation carries a value the rail cannot accept. Correct the field the response names and send the request again.	`decidedAt must be an RFC 3339 timestamp`, `movementDate must be a date in YYYY-MM-DD form`, `id must be a uuid`, or the rule the command breaks

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 service could not prove this command unique; its outcome is undetermined — reconcile the original request before retrying, and never retry it with a new key`
SILOC-0023	This deployment has no send leg to Núclea, so it cannot send the requested message.	`internal error`
SILOC-0024	The send leg to Núclea is not running on this deployment. Retry once it recovers.	`internal error`

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 X-Idempotency, and never retry under a new one.

Integration

Connectivity

Homologation

Participants

Cycles and settlement

Transfers

Collateral

Card route

Entries and statements

Advices and notices

Alerts and audit

Schedule

Error handling

SILOC error list

400, 413, 415: Request body refused

401: Unidentified caller

403: Refused caller

404: Not found

409: Conflicts

422: Validation errors

500: Server errors

503: Rail cannot answer

​400, 413, 415: Request body refused

​401: Unidentified caller

​403: Refused caller

​404: Not found

​409: Conflicts

​422: Validation errors

​500: Server errors

​503: Rail cannot answer

400, 413, 415: Request body refused

401: Unidentified caller

403: Refused caller

404: Not found

409: Conflicts

422: Validation errors

500: Server errors

503: Rail cannot answer