> ## 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 errores de SRC

> Lerian SRC devuelve respuestas de error estructuradas. Consulta cada código de error de SRC, qué significa y el estado HTTP que lleva.

**Formato de error**

Las operaciones de Lerian SRC devuelven los errores como problem details de RFC 9457 con el tipo de medio `application/problem+json`:

<CodeGroup>
  ```json JSON theme={null}
  {
    "code": "SRC-0002",
    "correlationId": "req-7a3f9c2e",
    "detail": "consultation domain validation failed: document: check digits are invalid for the declared documentType",
    "instance": "/v1/src/consultations",
    "status": 422,
    "title": "Unprocessable Entity",
    "traceId": "a1b2c3d4",
    "type": "https://errors.lerian.studio/v1/SRC-0002",
    "violations": [
      {
        "code": "SRC-0002",
        "field": "document",
        "reason": "check digits are invalid for the declared documentType"
      }
    ]
  }
  ```
</CodeGroup>

**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>`.
* **`title`** – El texto del estado HTTP (por ejemplo, `Unprocessable Entity`).
* **`status`** – El código de estado HTTP.
* **`detail`** – Una explicación legible de esta ocurrencia. En las respuestas `5xx`, el detail dice `internal error`. Decide la rama con `code` en su lugar.
* **`instance`** – La ruta de la solicitud.
* **`traceId`** – El identificador de traza de la solicitud.
* **`correlationId`** – El identificador de correlación con alcance de la solicitud.
* **`code`** – Un identificador estable para el error. Decide la rama con este campo. Dos errores pueden compartir un estado y aun así diferir aquí. `SRC-0003` y `SRC-0101` responden ambos `409`.
* **`violations`** – Una lista de errores de validación por campo, cada uno con un `field`, un `reason` y un `code` opcional.
* **`details`** – Contexto estructurado opcional sobre el error.

## Errores de solicitud

***

Estos errores se aplican a la solicitud misma.

| `code` | Descripción | Estado |
| - | - | - |
| SRC-0001 | Solicitud mal formada. Un valor de la solicitud no se puede interpretar, por ejemplo una fecha, un cursor o un id de consulta. Una solicitud `POST /v1/src/consultations` sin el header `X-Idempotency` también responde este código. Un cuerpo de solicitud de más de 1 MiB responde `413`, y un método que la ruta no acepta responde `405`. | 400, 405, 413 |
| SRC-0002 | La validación falló. `violations` indica los campos con error. Por ejemplo, los dígitos verificadores del CPF o del CNPJ no son válidos, `documentType` no corresponde al documento, un tipo de protección está fuera del catálogo o falta la motivación. Una solicitud de consulta rechazada no envía nada a BACEN. | 422 |
| SRC-0003 | Conflicto de idempotencia. La clave `X-Idempotency` ya se usó con un cuerpo de solicitud diferente. Usa una clave nueva, o envía de nuevo el cuerpo original. La misma clave con el mismo cuerpo responde `202` con el id de la consulta original. | 409 |
| SRC-0004 | Rol del consultado no válido. `subjectRole` no es `individual`, `company`, `holder` ni `representative`. Envía uno de estos valores, u omite el campo para que Lerian SRC tome el rol de `documentType`. | 422 |
| SRC-0005 | El rol del consultado no corresponde al documento. `individual`, `holder` y `representative` necesitan un CPF, y `company` necesita un CNPJ. | 422 |
| SRC-0006 | Vínculo con la empresa obligatorio. `subjectRole` es `holder` o `representative`, y la solicitud no tiene `companyConsultationId`. Envía el id que devolvió la consulta de la empresa con su `202`. | 422 |
| SRC-0007 | Vínculo con la empresa no permitido. La solicitud envía `companyConsultationId` con `subjectRole` `individual` o `company`. Quita el campo, o usa `holder` o `representative`. | 422 |
| SRC-0008 | Consulta de la empresa no usable. `companyConsultationId` no indica una consulta de CNPJ de este despliegue. | 422 |
| SRC-0201 | Una solicitud sin un token válido devuelve `401`. Un token de otro tipo devuelve `401` con el código `SRC-0201`. | 401 |
| SRC-0202 | Cada operación necesita un permiso en el producto `src`. Un token sin ese permiso devuelve `403` con el código `SRC-0202`. | 403 |
| SRC-0301 | No encontrado. El recurso que indica la solicitud no existe, por ejemplo una consulta o un caso de operador. El cierre de un caso de operador que no está abierto, y una ruta que no corresponde a ningún endpoint, también responden este código. | 404 |
| SRC-0401 | Rate limit excedido. Llegaron demasiadas solicitudes desde tu dirección en la ventana actual. Reintenta después del intervalo del header `Retry-After`. | 429 |

## Errores de registro de la institución y de evidencias

***

Estos errores se aplican a los registros de la institución y a las correcciones de la pista de evidencias.

| `code` | Descripción | Estado |
| - | - | - |
| SRC-0101 | Registro de la institución ya registrado. La consulta ya tiene un registro de la institución. Un registro no puede cambiar, y una consulta guarda un registro de cualquiera de los dos tipos. El `detail` puede indicar el tipo registrado. | 409 |
| SRC-0102 | Registro de la institución no aplicable. La consulta no se completó con una restricción activa, así que no acepta un registro de la institución de ningún tipo. | 409 |
| SRC-0104 | Posición de la pista ocupada. Una corrección concurrente de la misma pista de evidencias ocupó la posición. No se escribió nada. Reintenta la corrección. | 409 |

## Errores de disponibilidad

***

Estos errores significan que Lerian SRC no pudo completar la solicitud. Cuando BACEN o el canal de mensajería no está disponible, Lerian SRC sigue aceptando consultas, y estas quedan en `pending`.

| `code` | Descripción | Estado |
| - | - | - |
| SRC-1002 | No está listo. Lerian SRC no puede llegar a una dependencia que necesita para atender la solicitud. Reintenta más tarde. | 503 |
| SRC-1003 | Contención de bloqueo. Un bloqueo de la base de datos no estuvo disponible dentro del límite de tiempo de Lerian SRC. No se escribió nada, y la solicitud era correcta. Reintenta. | 504 |
| SRC-1004 | Presupuesto de la solicitud agotado. La solicitud no se completó dentro del presupuesto de tiempo de 15 segundos de Lerian SRC. Reintenta después del intervalo del header `Retry-After`. Antes de reintentar una corrección de evidencia, lee la pista de evidencias. | 503 |
| SRC-9000 | Error interno. Una falla inesperada. El `detail` dice `internal error`. | 500 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.