> ## 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.

# SRC error list

> Lerian SRC returns structured error responses. Look up each SRC error code, what it means, and the HTTP status it carries.

**Error format**

Lerian SRC operations return errors as RFC 9457 problem details with the `application/problem+json` media type:

<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>

**Field definitions**

* **`type`** – A URI that identifies the error in the Lerian error catalog, built as `https://errors.lerian.studio/v1/<code>`.
* **`title`** – The HTTP status text (for example, `Unprocessable Entity`).
* **`status`** – The HTTP status code.
* **`detail`** – A human-readable explanation of this occurrence. For `5xx` responses, the detail reads `internal error`. Branch on `code` instead.
* **`instance`** – The path of the request.
* **`traceId`** – The trace identifier of the request.
* **`correlationId`** – The request-scoped correlation identifier.
* **`code`** – A stable identifier for the error. Branch on this field. Two errors can share a status and still differ here. `SRC-0003` and `SRC-0101` both answer `409`.
* **`violations`** – A list of field-level validation errors, each with a `field`, a `reason`, and an optional `code`.
* **`details`** – Optional structured context about the error.

## Request errors

***

These errors apply to the request itself.

| `code` | Description | Status |
| - | - | - |
| SRC-0001 | Malformed request. A value in the request cannot be parsed, for example a date, a cursor, or a consultation id. A `POST /v1/src/consultations` request without the `X-Idempotency` header also answers this code. A request body over 1 MiB answers `413`, and a method that the path does not accept answers `405`. | 400, 405, 413 |
| SRC-0002 | Validation failed. `violations` names the fields at fault. For example, the CPF or CNPJ check digits are invalid, `documentType` does not match the document, a protection type is outside the catalog, or the motivation is missing. A refused consultation request sends nothing to BACEN. | 422 |
| SRC-0003 | Idempotency conflict. The `X-Idempotency` key was already used with a different request body. Use a new key, or send the original body again. The same key with the same body answers `202` with the original consultation id. | 409 |
| SRC-0004 | Invalid subject role. `subjectRole` is not `individual`, `company`, `holder`, or `representative`. Send one of these values, or omit the field so that Lerian SRC takes the role from `documentType`. | 422 |
| SRC-0005 | Subject role and document mismatch. `individual`, `holder`, and `representative` need a CPF, and `company` needs a CNPJ. | 422 |
| SRC-0006 | Company link required. `subjectRole` is `holder` or `representative`, and the request has no `companyConsultationId`. Send the id that the company consultation returned with its `202`. | 422 |
| SRC-0007 | Company link not allowed. The request sends `companyConsultationId` with `subjectRole` `individual` or `company`. Remove the field, or use `holder` or `representative`. | 422 |
| SRC-0008 | Company consultation not usable. `companyConsultationId` does not name a CNPJ consultation of this deployment. | 422 |
| SRC-0201 | A request without a valid token returns `401`. A token of another type returns `401` with code `SRC-0201`. | 401 |
| SRC-0202 | Each operation needs one permission on the `src` product. A token without that permission returns `403` with code `SRC-0202`. | 403 |
| SRC-0301 | Not found. The resource that the request names does not exist, for example a consultation or an operator case. A closure of an operator case that is not open, and a path that matches no route, also answer this code. | 404 |
| SRC-0401 | Rate limit exceeded. Too many requests arrived from your address in the current window. Retry after the interval in the `Retry-After` header. | 429 |

## Institution record and evidence errors

***

These errors apply to institution records and to corrections of the evidence trail.

| `code` | Description | Status |
| - | - | - |
| SRC-0101 | Institution record already registered. The consultation already has an institution record. A record cannot change, and a consultation holds one record of either kind. The `detail` can name the kind that is on record. | 409 |
| SRC-0102 | Institution record not applicable. The consultation did not complete with an active restriction, so it does not accept an institution record of either kind. | 409 |
| SRC-0104 | Trail position taken. A concurrent correction of the same evidence trail took the position. Nothing was written. Retry the correction. | 409 |

## Availability errors

***

These errors mean that Lerian SRC could not complete the request. When BACEN or the messaging channel is unavailable, Lerian SRC still accepts consultations, and they stay `pending`.

| `code` | Description | Status |
| - | - | - |
| SRC-1002 | Not ready. Lerian SRC cannot reach a dependency that it needs to serve the request. Retry later. | 503 |
| SRC-1003 | Lock contention. A database lock was not available within the time limit of Lerian SRC. Nothing was written, and the request was correct. Retry. | 504 |
| SRC-1004 | Request budget elapsed. The request did not complete within the 15-second time budget of Lerian SRC. Retry after the interval in the `Retry-After` header. Before you retry an evidence correction, read the evidence trail. | 503 |
| SRC-9000 | Internal error. An unexpected failure. The `detail` reads `internal error`. | 500 |


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