SRC error list

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

{
  "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"
    }
  ]
}

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

Consultations

Institution records

Evidence

Dashboard

Credentials

Operator cases

Error handling

SRC error list

Request errors

Institution record and evidence errors

Availability errors

​Request errors

​Institution record and evidence errors

​Availability errors

Request errors

Institution record and evidence errors

Availability errors