Lista de errores de SILOC

Formato de error SILOC devuelve los errores como detalles de problema RFC 9457:

{
  "type": "https://errors.lerian.studio/v1/SILOC-0007",
  "title": "Not Found",
  "status": 404,
  "detail": "participant not found",
  "code": "SILOC-0007"
}

Definiciones de campos

type – Un URI que identifica el error en el catálogo de errores de Lerian, construido como https://errors.lerian.studio/v1/<code>. Este URI repite code, por lo que no separa dos estados que comparten un código.
title – El texto del estado HTTP (por ejemplo, Not Found).
status – El código de estado HTTP.
detail – Una explicación legible para esta ocurrencia. Un 500 y un SILOC-0023 reemplazan el texto por internal error, de modo que la causa interna permanece dentro del riel. El texto varía según la ocurrencia, y un 403 puede llevar el mensaje que reportó el servicio de autorización. No distingas por él.
code – El código estable y procesable por máquina (SILOC-NNNN). Distingue por el par de status y code, no solo por code. Un código puede aparecer bajo más de un estado, y cada estado necesita una acción diferente. Por ejemplo, SILOC-0022 es un 400 para un cuerpo que no es JSON válido y un 422 para un valor que rompe una regla de dominio. Una solicitud que falla la validación de esquema lleva SILOC-0022, y errors nombra los campos con el fallo.
errors – Una lista opcional de detalles en el nivel de campo, cada uno con el location que leyó, un message y el value encontrado allí. Un rechazo de la puerta de autorización o de idempotencia lleva en su lugar una lista violations vacía.

Las tablas siguientes listan los códigos que devuelve SILOC, agrupados por estado HTTP.

400, 413, 415: Cuerpo de la solicitud rechazado

Estado	`code`	Descripción	`detail`
400	SILOC-0022	El cuerpo de la solicitud falta o no es un JSON válido. Envía un cuerpo JSON que siga el schema de la operación.	`request body is required`, `validation failed`
413	SILOC-0022	El cuerpo de la solicitud alcanzó el límite de 1 MiB. Envía un cuerpo más pequeño.	`request body is too large limit=1048576 bytes`
415	SILOC-0022	La solicitud declara un `Content-Type` que no es JSON. Envía el cuerpo como `application/json`.	`validation failed`

401: Solicitante no identificado

`code`	Descripción	`detail`
SILOC-0004	La solicitud llegó sin un token bearer, o con una credencial que el servicio de autorización no acepta.	`Missing Token`, o `Unauthorized`
SILOC-0003	Una solicitud que cambia el estado llegó a la puerta de idempotencia sin un solicitante identificado al que atribuir la `X-Idempotency`.	`authenticated principal unavailable`
SILOC-0401	Una operación de certificado llegó al riel sin una identidad de solicitante que registrar.	`authorized actor identity is unavailable`

403: Solicitante rechazado

`code`	Descripción	`detail`
SILOC-0005	El servicio de autorización rechazó a este solicitante para el recurso y la acción que la solicitud especifica.	`Forbidden`, o el mensaje que reportó el servicio de autorización

404: No encontrado

`code`	Descripción	`detail`
SILOC-0007	La ruta o la consulta nombró un recurso que el riel no tiene. Verifica el identificador, o lista la colección para encontrar uno válido.	`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`, `no card message with that id`, `no card command with that id`

409: Conflictos

`code`	Descripción	`detail`
SILOC-0009	La solicitud choca con un estado que el riel ya tiene, o con un comando que ya usó esta `X-Idempotency`. Vuelve a leer el estado actual antes de reintentar.	`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: Errores de validación

`code`	Descripción	`detail`
SILOC-0022	La solicitud está bien formada, pero rompe una regla de dominio, o lleva un valor que el riel no puede leer. Corrige el campo que nombra la respuesta y envía la solicitud de nuevo.	`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`, `decidedAt must be an RFC 3339 timestamp`, `movementDate must be a date in YYYY-MM-DD form`, `id must be a uuid`, o la regla que rompe un comando de tarjeta
SILOC-0025	Una decisión `LTR0002` o `LTR0008` llegó a las 17h30 de Brasilia o después, cuando cierra el ciclo LBTR del día de movimiento. El riel no almacenó nada.	`the LBTR cycle of today's movement day closed at 17h30 Brasília; the câmara takes no LBTR decision until the next cycle`

500: Errores del servidor

`code`	Descripción	`detail`
SILOC-0500	Un fallo inesperado del servidor. El riel oculta la causa y devuelve un texto fijo. Reintenta la solicitud, y cita el identificador de traza de la respuesta si el fallo persiste.	`internal error`

503: El riel no puede responder

`code`	Descripción	`detail`
SILOC-0001	El riel no pudo llegar a una decisión sobre este solicitante. El servicio de autorización no respondió, o la implementación no puede autorizar con su configuración actual.	`Service Unavailable`
SILOC-0002	El riel no pudo probar que el comando fuera único, por lo que el resultado del comando quedó indeterminado.	`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	Esta implementación no tiene un tramo de envío hacia Núclea, por lo que no puede enviar el mensaje solicitado.	`internal error`
SILOC-0024	El tramo de envío hacia Núclea no está en ejecución en esta implementación, o el queue manager de SILOC de Núclea no es accesible. El riel no almacenó nada. Reintenta con el mismo `X-Idempotency` cuando se recupere.	`internal error`, o `Núclea is unavailable: the SILOC queue manager cannot be reached, so the message was not stored; retry once it recovers`

Un 503 que lleva SILOC-0002 no te dice que el comando fue rechazado. El riel responde con él tanto antes de que el comando se ejecute como después de que se confirme, de modo que el comando ya podría haber surtido efecto. Concilia primero la solicitud original. Cuando reintentes, envía la misma X-Idempotency, y nunca reintentes bajo una nueva.

Integración

Conectividad

Homologación

Participantes

Ciclos y liquidación

Transferencias

Garantías

Ruta de tarjetas

Asientos y extractos

Avisos y notificaciones

Alertas y auditoría

Programación

Manejo de errores

Lista de errores de SILOC

400, 413, 415: Cuerpo de la solicitud rechazado

401: Solicitante no identificado

403: Solicitante rechazado

404: No encontrado

409: Conflictos

422: Errores de validación

500: Errores del servidor

503: El riel no puede responder

​400, 413, 415: Cuerpo de la solicitud rechazado

​401: Solicitante no identificado

​403: Solicitante rechazado

​404: No encontrado

​409: Conflictos

​422: Errores de validación

​500: Errores del servidor

​503: El riel no puede responder

400, 413, 415: Cuerpo de la solicitud rechazado

401: Solicitante no identificado

403: Solicitante rechazado

404: No encontrado

409: Conflictos

422: Errores de validación

500: Errores del servidor

503: El riel no puede responder