Consignado error list

Lerian Consignado returns structured error responses. Look up each CLT error code, what it means, and which reason codes come straight from Dataprev.

Error format

Lerian Consignado returns errors as RFC 9457 problem details with the application/problem+json media type:

JSON

{
  "code": "CLT-0006",
  "detail": "The worker's authorization is outside its validity window, so their payroll data can no longer be read under it. Obtain a fresh worker authorization and send its evidence; repeating this request cannot succeed.",
  "status": 422,
  "title": "Unprocessable Entity",
  "type": "https://errors.lerian.studio/v1/CLT-0006"
}

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. On a 5xx response Consignado sanitizes the detail to internal error, so an internal cause stays out of the body. A 5xx code that names an upstream fault or an unknown outcome keeps a detail written for you, such as DATAPREV_TIMEOUT. Branch on code and on the status, not on the detail.
• code – A stable identifier for the error. The tables below list the CLT-NNNN codes and the named codes that several operations share. Some operations answer codes of their own, such as CURSOR_EXPIRED on the registration inventory sweep. See Operation codes. A request that fails schema validation carries no code: it answers 422 with the detail validation failed, or 400 when the body cannot be parsed, and the errors list names each field.
• errors – Optional list of individual error details, each with a location, a message, and a value.
• instance – The trace ID of the request, when the gateway traced it. Quote it when you report a failure to Lerian.
• upstream – The error an upstream system returned, which the gateway relays. It comes from Dataprev on a rail operation, and from the Streaming Hub on a subscription operation. It holds that system’s code and message, and it survives the 5xx sanitization that clears detail. See Dataprev reason codes.
• refusal – On a bid refusal: the reason the gateway recorded for the bid, with its source, field, rule, and detail. A refusal from Dataprev also carries Dataprev’s code.

400: Bad request

---

code	Description	detail
CLT-0001	Invalid request. For example, a credentials request carries a requester code that is not three digits, or a certificate and key that are not a valid PEM pair. A request with an X-Idempotency key longer than the operation accepts also gets this code. A disbursement confirmation, an FGTS guarantee execution, a contract correction, and a command that answers RAIL_COMMAND_* codes answer a key that is too long with 422. A contract import with a booking takes a key of at most 121 bytes: a key of 122 to 128 bytes answers 422 CLT-0006. A request that fails schema validation carries no code.	—
CLT-0011	Request failed. The fallback code for a client-side refusal with no entry of its own.	Names the refusal.

401: Unauthorized

---

code	Description	detail
CLT-0003	Unauthorized. The request carried no valid bearer token, or the gateway could not resolve a tenant from it.	Unauthorized, or a sentence that names the cause, such as The bearer token was not accepted.

403: Forbidden

---

code	Description	detail
CLT-0004	Forbidden. The authenticated caller does not hold permission for this operation. A caller that acts for an originador or a fund also gets this code on a contract that belongs to another party.	Forbidden

404: Not found

---

code	Description	detail
CLT-0005	Not found. The record the request named does not exist for this tenant. A retained artifact owned by another tenant answers the same way.	Not Found, The requested resource was not found., or a sentence that names what is missing, such as contract is not an averbação of this tenant

409: Conflict

---

code	Description	detail
CLT-0007	Conflict. The request conflicts with the current state of the record.	Conflict, or the sentence for the conflict, such as an identical request is already in flight.

CLT-0007 with the detail an identical request is already in flight marks a request the gateway has not finished. Retry that request under the same idempotency key.

Command conflicts answer a named code in place of CLT-0007, so a client can tell them apart. Read code and detail together before you retry. These code spellings are part of the wire contract and do not change.

code	Description	detail
FGTS_EXECUTION_PAYLOAD_MISMATCH	This idempotency key already holds a different FGTS guarantee execution.	This idempotency key already holds a different FGTS guarantee execution. Resend the original request under this key to replay it, or use a new key for a different execution.
FGTS_EXECUTION_OUTCOME_UNRESOLVED	The execution held under this idempotency key has no known outcome yet, so it cannot be replayed.	The FGTS guarantee execution held under this idempotency key has no known outcome yet, so it cannot be replayed. Executing the same contract under a new key risks moving the money twice.
FGTS_EXECUTION_ALREADY_REFUSED	The execution held under this idempotency key was refused, so a corrected request needs a new key.	The FGTS guarantee execution held under this idempotency key was refused. This key can only ever return that refusal, so a corrected request needs a new key.
FGTS_EXECUTION_CONTRACT_TAKEN	This contract’s FGTS guarantee already ran under another idempotency key. This request did not execute.	This contract’s FGTS guarantee was already executed under another idempotency key, and a guarantee is executed once. This request was not executed.
BID_SOLICITACAO_TAKEN	The solicitação already carries a bid from this institution.	This solicitação already carries a bid from this institution, and a solicitação takes one. Read the bid book for the outcome of the bid that holds it.
BID_PROPOSAL_SLOT_TAKEN	An earlier submission holds the proposal position, so this bid was not recorded.	A proposal position in this bid is already held by an earlier submission, so this bid was not recorded. Read the bid book for the outcome of the submission that holds it.
AVERBACAO_CLAIM_CONFLICT	This contract’s averbação is already claimed under another idempotency key.	This contract’s averbação is already claimed under another idempotency key. Follow the claim that exists instead of opening a second one.
AVERBACAO_ARTIFACT_CONFLICT	A different document is already retained for this contract’s averbação. This request did not apply.	A different document is already retained for this contract’s averbação, and a retained document is never replaced. This request was not applied.
AVERBACAO_NOT_ACCEPTED	The documentation needs an averbação that Dataprev accepted, and this contract has none. The refusal is final only when the averbação reads rejected. The tenant’s credential reads it at GET .../averbacao. An originador or fund credential resends the same averbação body under a new key.	The documentation needs an averbação Dataprev accepted, and this contract has none: read GET …/averbacao. Nothing was sent to Dataprev.
AVERBACAO_DOCUMENTATION_CONFLICT	This contract holds documentation that Dataprev accepted or that is on its way. A contract takes one accepted documentation.	This contract already holds documentation Dataprev accepted or that is on its way, and a contract takes one accepted documentation: follow the existing one. Nothing was sent to Dataprev.
AVERBACAO_EXCLUDED	An exclusion of this averbação was requested, or the contract left the registry, so the gateway accepts no documentation for it. If Dataprev rejects the exclusion, the same documentation goes through.	An exclusion of this contract was requested and Dataprev has not rejected it (read GET …/exclusion), or the contract left the registry: a refinanciamento, renegociação or portability exclusion recorded here took it off, or Dataprev showed it excluded or ended outside this gateway (read dataprev_follow_up in GET …/averbacao). No documentation is accepted for it, and nothing was sent to Dataprev.
AVERBACAO_HELD_BY_ANOTHER_SENDER	A credential of another kind sent this same request first, and it has not reached Dataprev. Only a credential of that kind can resume it, by sending it again.	A credential of another nature (bancarizador, fundo or originador) sent this same request first and it has not reached Dataprev: only a credential of that nature resumes it, by sending it again. Nothing was sent to Dataprev.
EXCLUSION_AUTHORITY_CONFLICT	This contract’s exclusion is already recorded under another authority. This request did not apply.	This contract’s exclusion is already recorded under another authority, and an exclusion has no undo. This request was not applied.
EXCLUSION_DOCUMENTATION_UNDERWAY	The averbação’s documentation is recorded or on its way to Dataprev, so the averbação is not confirmed and cannot be excluded yet.	This contract’s documentation is already recorded or on its way to Dataprev, so its averbação is not confirmed yet and cannot be excluded now. While GET …/averbacao reads attachment_pending, the recorded documentation completes only when the same documentation is sent again to POST …/ccb-attachment; exclude the contract once it reads confirmed. Nothing was sent to Dataprev.
EXCLUSION_BOOKING_IDENTITY_INCOMPLETE	The booking the gateway holds for this contract lacks the worker or employer identity that Manual 003 requires. No request can correct it: report it to Lerian with the instance.	The booking the gateway holds for this contract lacks the worker or employer identity M003 requires, so the exclusion cannot be sent. Correct the booking; no change to this request can succeed.
RAIL_COMMAND_CLAIM_CONFLICT	This command is already claimed for this contract under another idempotency key.	This command is already claimed for this contract under another idempotency key. Follow the claim that exists instead of opening a second one.
RAIL_COMMAND_PAYLOAD_MISMATCH	This idempotency key already holds a different command for this contract.	This idempotency key already holds a different command for this contract. Resend the original request under this key to replay it, or use a new key for a different command.
RAIL_COMMAND_ALREADY_REFUSED	Dataprev refused the command held under this idempotency key, so a corrected request needs a new key.	The command held under this idempotency key was refused by Dataprev. This key can only ever return that refusal, so a corrected request needs a new key.
RAIL_COMMAND_OUTCOME_UNRESOLVED	The command held under this idempotency key has no known outcome yet. Do not send it under a new key.	The command held under this idempotency key has no known outcome yet, so it cannot be replayed. Read GET /v1/consignado/rail-commands; do not send it under a new key.
RAIL_COMMAND_ANSWER_NOT_RETAINED	This command already committed for this contract, and its original answer was not kept.	This command already committed for this contract, but its original answer was not kept, so there is nothing to replay. Read the contract’s current state rather than sending it again.
REVERSAO_WINDOW_EXPIRED	The window for reversing this refinancing has closed, so no correction reopens it.	The window for reversing this refinancing has closed, so the reversal can no longer be requested. No correction to this request can reopen it.
DISBURSEMENT_PAYMENT_CONFLICT	This payment reference already holds a confirmation with a different amount or payment time. File a disbursement correction to change it.	This payment_reference already holds a confirmation with a different amount or paid_at, and a confirmation is immutable. File a disbursement correction (correction_type=disbursement) to change it.
CONTRACT_ALREADY_REGISTERED	The contract import names a contract this tenant already holds: in its saldo devedor book, for an import without a booking, or in its averbação book, for an import with a booking.	Names the book that holds the contract and the next step: read the obligation that exists, or resend the original import to replay it.
DATAPREV_CREDENTIAL_REQUIRED	The tenant has no Dataprev credential in custody, so no rail operation can run for it.	This tenant has no Dataprev credential in custody, so the gateway cannot act for it on the rail. Provision the credential first; no correction to this request can succeed until then.
DATAPREV_CREDENTIAL_REJECTED	Dataprev refused the tenant’s OAuth client credentials.	Dataprev refused this tenant’s OAuth client credentials. Correct them in the gateway’s credential custody; retrying unchanged cannot succeed.
DATAPREV_CREDENTIAL_REVOKED	The tenant’s Dataprev credentials were revoked. Rail operations answer this code, and so do certificate, OAuth credential, and requester code uploads.	This tenant’s Dataprev credentials were revoked, and a revocation is permanent: no request can use or replace them.

After DATAPREV_CREDENTIAL_REQUIRED, upload the tenant’s Dataprev certificate, OAuth credentials, and requester code, then send the request again. After DATAPREV_CREDENTIAL_REJECTED, correct the tenant’s OAuth client credentials, then send a read again. A write may have parked its command: see Operate Lerian Consignado before you send it again.

410: Gone

---

The paginated registration inventory sweep issues a cursor with a limited retry window.

code	Description	detail
CURSOR_EXPIRED	Gone. The cursor’s retry window has passed, so the sweep it belonged to cannot continue. Start a new sweep instead.	The cursor retry window has expired.

413: Request entity too large

---

code	Description	detail
CLT-0010	Request entity too large. The request payload is larger than the endpoint accepts, or a command body holds more JSON tokens than the command accepts.	Names the limit the request crossed, in bytes or in JSON tokens.

An averbação body that carries the signed CCB, the evidence pack, the signature evidence, or data_hora_assinatura is refused. It answers 413 at 1 MiB or more, and 422 with the detail validation failed below that. Send them to POST /v1/consignado/contracts/{numero_contrato}/ccb-attachment once Dataprev accepts the averbação.

422: Unprocessable entity

---

code	Description	detail
CLT-0006	Unprocessable entity. The gateway read the request and refuses it in its current form. A deterministic Dataprev rejection answers here too, and carries upstream.	The reason to act on, such as obtaining a fresh worker authorization.

Some refusals answer a named code in place of CLT-0006. Nothing reached Dataprev. The description says what to do next.

code	Description	detail
IDEMPOTENCY_KEY_REUSE	The X-Idempotency key is spent on a different request. Send the changed request under a new key.	The X-Idempotency key was already used with a different request; send a new key for a changed request.
FUNDO_NOT_REGISTERED	fundo_ref names no fund registered for this tenant. Correct fundo_ref.	fundo_ref does not name a fund registered for this tenant
FUNDO_DEACTIVATED	The fund that fundo_ref names no longer accepts new credit.	the named fund is deactivated and does not accept new credit
FIRST_DEDUCTION_BEFORE_COMPETENCIA	data_primeiro_desconto falls in a month before first_deduction_competencia. Correct the dates.	Names the rule.
DECLARED_DATES_OUT_OF_ORDER	The declared dates break an order the booking requires. Correct the dates.	Names the rule.
FORMALIZATION_DEADLINE_EXCEEDED	data_hora_assinatura is after formalization_deadline. When the documentation answers it, exclude the averbação, then formalize the contract again.	Names the rule.
BOOKING_FIELD_INVALID	Lender cannot read a booking field.	Names the field.
DECLARED_TERMS_INCONSISTENT	The declared amounts or rates contradict each other. Correct the terms.	Names the rule.
MARGIN_SNAPSHOT_INCONSISTENT	margin_snapshot does not hold installment_amount. Read the margin again or price the contract again.	Names the rule.
CONTRACT_NOT_BOOKABLE	Lender cannot book this contract at all. Send the request without the booking block.	Names the rule.
BID_ORIGINADOR_UNKNOWN	The originador the bid is placed for is not registered for this tenant.	The originador this bid is placed for is not registered for this tenant. A bancarizador names it in originadorRef; an originador credential bids under its own reference, which must be registered before it can bid.
BID_ORIGINADOR_INACTIVE	The originador the bid is placed for can no longer act for this tenant.	The originador this bid is placed for may no longer act for this tenant. A bancarizador names it in originadorRef; an originador credential bids under its own reference, which must be reactivated before it can bid again.
BID_SOLICITACAO_UNKNOWN	The gateway holds no discovered solicitação under this identifier. Retry after its consignado.solicitacao.received event arrives.	The gateway holds no discovered solicitação under this identifier. Retry after its consignado_solicitacao.received event arrives; nothing was recorded.
BID_NO_PROPOSTA_LEFT	A resumed bid has no proposta left to send again. Place a new bid.	No proposta is left to retry under this idempotency key: either its validadeProposta has passed and Dataprev will no longer accept it, or its stored payload was already erased by this service’s retention. Place a new bid if the solicitação is still open.
PORTABILIDADE_WINDOW_EXPIRED	The portability window has passed: the 20 calendar days to complete an outbound portability, or the validity of the solicitação that a portability auction response answers.	Names the window.

The booking codes, from FIRST_DEDUCTION_BEFORE_COMPETENCIA to CONTRACT_NOT_BOOKABLE, apply only to a contract sent with the booking block. An averbação answers every booking code except FORMALIZATION_DEADLINE_EXCEEDED. Its documentation answers only DECLARED_DATES_OUT_OF_ORDER and FORMALIZATION_DEADLINE_EXCEEDED. A contract import with a booking answers every booking code except FIRST_DEDUCTION_BEFORE_COMPETENCIA.

A command sent again under an idempotency key that an earlier request already spent can answer one of four named codes. The earlier request can already have reached Dataprev. Do not send the command again, under this key or a new one. Read the current state of the record the command changes. A portability auction response is the exception: its reference explains how a resend under a new key reveals the outcome.

code	Description	detail
IDEMPOTENCY_STATE_UNRECOGNISED	The record held under this key was written by a newer version of the service.	An earlier request spent this idempotency key with a record written by a newer version of this service; reconcile the original request and do not retry under a new key.
IDEMPOTENCY_RECORD_UNREADABLE	The record held under this key cannot be read.	An earlier request spent this idempotency key with a record this service cannot read; reconcile the original request and do not retry under a new key.
IDEMPOTENCY_OUTCOME_UNRECORDED	The earlier request under this key has no recorded outcome.	An earlier request spent this idempotency key and its outcome was not recorded; reconcile the original request and do not retry under a new key.
IDEMPOTENCY_REPLAY_UNAVAILABLE	The earlier request under this key completed, and its answer cannot be replayed.	An earlier request with this idempotency key completed and its response was delivered once, but it cannot be replayed; do not resend, reconcile the resource the command mutates, and do not retry under a new key.

429: Too many requests

---

code	Description	detail
CLT-0009	Too many requests. The caller exceeded its request budget.	Too many requests were sent in a given amount of time.

Wait for the time the Retry-After header gives, then send the request again.

500: Internal server error

---

code	Description	detail
CLT-0002	Internal server error. An unexpected failure inside the gateway.	internal error

501: Not implemented

---

A 501 answers an operation your deployment has not enabled. The routes stay mounted, so the answer arrives per request rather than as a missing path. These operations answer 501 until your deployment enables them:

• contract artifact downloads
• contract corrections
• bid submission
• operations that reach Dataprev

Dataprev credential revocation answers 501 on a deployment whose credentials are static.

The detail reads internal error, because Consignado sanitizes the detail on a 5xx response. Credential revocation is the exception: its detail says that the credentials are static. Branch on the status.

502: Bad gateway

---

code	Description	detail
DATAPREV_INVALID_RESPONSE	Dataprev returned data for a read that the gateway cannot use. Nothing changed. Retry later, or narrow the window of the read.	Dataprev returned data for this read that the gateway could not use; nothing was changed. Retry later or narrow the window, quoting this instance if it persists.

503: Service unavailable

---

code	Description	detail
CLT-0008	Service unavailable. The gateway cannot serve the request now. Its own storage or credential custody is unavailable, or its pacing of calls to Dataprev held the request past its deadline. Send the same request again shortly, under the same idempotency key.	A sentence that names the cause, or internal error.
DATAPREV_UNAVAILABLE	Dataprev answered with a retry-later fault, or did not answer. Retry later under the same idempotency key.	Dataprev is unavailable for this request right now; the upstream member carries its own code when it sent one. Retry later, reusing the same X-Idempotency key on a command.
OUTCOME_UNKNOWN	The gateway cannot tell if the request took effect. It failed to record the outcome, or Dataprev’s acknowledgement of a bid was ambiguous. Retry only under the same idempotency key.	The gateway could not record this request’s outcome, so whether it took effect is unknown. Never resend it under a new key: retry under the SAME X-Idempotency key, and if that retry answers IDEMPOTENCY_OUTCOME_UNRECORDED, reconcile the original request.
STREAMING_HUB_UNAVAILABLE	The Streaming Hub behind the subscription operations is unavailable.	The streaming hub is unavailable. Retry later, reusing the same X-Idempotency key on a change.
TENANT_MANAGER_UNAVAILABLE	The Tenant Manager is unavailable, so the gateway cannot resolve your tenant. Only a multi-tenant deployment answers this code.	tenant manager is unavailable; retry the request later
AUT-0033	The Access Manager did not decide on this request.	The Access Manager did not decide this request. Please wait a moment and try again.

A DATAPREV_UNAVAILABLE or DATAPREV_TIMEOUT response also carries upstream when Dataprev sent its own code and message.

504: Gateway timeout

---

code	Description	detail
DATAPREV_TIMEOUT	Dataprev did not answer in time. If the request changes state at Dataprev, its outcome is unknown. Retry only under the same idempotency key.	Dataprev did not answer in time, so if this request changes state at Dataprev its outcome is unknown. Never resend it under a new key: retry under the SAME X-Idempotency key, and if that retry answers IDEMPOTENCY_OUTCOME_UNRECORDED, reconcile the original request.
STREAMING_HUB_TIMEOUT	The Streaming Hub behind the subscription operations did not answer in time.	The streaming hub did not answer in time. Retry, reusing the same X-Idempotency key on a change.
TENANT_MANAGER_TIMEOUT	The Tenant Manager did not answer in time. Only a multi-tenant deployment answers this code.	tenant manager did not answer in time; retry the request
AUT-1021	The Access Manager did not answer in time.	The Access Manager did not answer in time. Please try again.

Operation codes

---

Some operations answer codes of their own, named after the operation: FUNDO_*, ORIGINADOR_*, CESSAO_*, CEDED_CREDIT_*, SALDO_DEVEDOR_*, REGISTRO_B3_*, and the cursor and filter codes of the list operations. The API reference enumerates every code in the code field of its error schema.

The B3 instrument code operations, GET and PATCH /v1/consignado/contracts/{numero_contrato}/registro-b3, answer these codes.

code	Status	Description	detail
REGISTRO_B3_CONTRATO_NAO_ENCONTRADO	404	This tenant holds no contract with this number.	No such contract was found for this tenant.
REGISTRO_B3_NAO_INFORMADO	404	The contract holds no B3 instrument code yet.	The contract holds no registro B3 yet.
REGISTRO_B3_AVERBACAO_NAO_CONFIRMADA	409	The contract’s averbação is not confirmed. The gateway takes the code only after the averbação is confirmed.	The contract’s averbação is not confirmed.
REGISTRO_B3_JA_INFORMADO	409	The contract already holds a different code or registration date. The API offers no correction. Sending the same registro again answers 200.	The contract already holds a different registro B3.
REGISTRO_B3_DATA_REGISTRO_INVALIDA	422	dataRegistro is in the future or before the averbação.	dataRegistro must not be in the future nor before the averbação.
REGISTRO_B3_INTERNAL	500	An unexpected failure.	internal error
REGISTRO_B3_UNWIRED	501	This deployment does not record the B3 instrument code.	internal error
REGISTRO_B3_UNAVAILABLE	503	The store of the B3 instrument code is unavailable. Send the request again shortly.	internal error

Dataprev reason codes

---

Consignado relays Dataprev’s reason codes rather than mapping them onto codes of its own. That keeps a refusal readable against what Dataprev said. Read each reason code against Dataprev’s specification, not against this page. Dataprev can publish a code this page does not list, and the gateway still delivers it to you.

They reach you in two places.

On a refusal. The upstream member carries Dataprev’s own code and message. A refusal with several codes lists them comma-separated. The member holds Dataprev’s codes and sentences, bounded in length, rather than a response body. A 422 carries it for a deterministic rejection. DATAPREV_UNAVAILABLE and DATAPREV_TIMEOUT carry it for a retry-later fault.

A Dataprev refusal of a command in upstream stays under its idempotency key. So does a bid refusal, whatever its source. The same key returns the same refusal, so send a corrected request under a new key. A bid refused with source dataprev also holds its solicitação, so any new bid for that solicitação answers BID_SOLICITACAO_TAKEN.

A refusal the gateway makes on its own, with no upstream and no bid refusal member, does not keep the key, so a corrected request can go under the same key. An FGTS guarantee execution and a command that answers RAIL_COMMAND_* codes are the exception: they hold the key from before they call Dataprev. When a resend answers that an earlier request already holds the key, such as IDEMPOTENCY_KEY_REUSE or RAIL_COMMAND_PAYLOAD_MISMATCH, follow that code’s own instruction.

On contract and margin responses. Several response fields pair a Dataprev reason code with Dataprev’s own label for it. A margin read publishes blockType and ineligibilityReason, which spell the pair code and description. A contract read publishes motivo_exclusao, origem_averbacao, origem_exclusao, portabilidade_situacao, and situacao_bloqueio_garantia, which spell it codigo and descricao. Each field holds a numeric code and the text Dataprev returned beside it.

Treat the set as open. Map the reason codes your integration acts on, and pass the rest through with their labels, so a code you have not mapped yet stays readable to an operator.