> ## 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 erros do Consignado

> O Lerian Consignado retorna respostas de erro estruturadas. Consulte cada código de erro CLT, o que ele significa, e quais códigos de motivo vêm diretamente do Dataprev.

**Formato do erro**

O Lerian Consignado retorna erros como problem details RFC 9457, com o media type `application/problem+json`:

```json JSON theme={null}
{
  "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"
}
```

**Definições de campos**

* **`type`** – Uma URI que identifica o erro no catálogo de erros da Lerian. Construída como `https://errors.lerian.studio/v1/<code>`.
* **`title`** – O texto do status HTTP (por exemplo, `Unprocessable Entity`).
* **`status`** – O código de status HTTP.
* **`detail`** – Uma explicação legível por humanos desta ocorrência. Em uma resposta `5xx`, o Consignado sanitiza o detail para `internal error`, para que uma causa interna nunca apareça no corpo. Um código `5xx` que nomeia uma falha upstream ou um desfecho desconhecido mantém um detail escrito para você, como `DATAPREV_TIMEOUT`. Baseie sua lógica em `code` e no status, não no detail.
* **`code`** – Um identificador estável para o erro. As tabelas abaixo listam os códigos `CLT-NNNN` e os códigos nomeados que várias operações compartilham. Algumas operações respondem com códigos próprios, como `CURSOR_EXPIRED` na varredura de inventário de registros. Veja [Códigos por operação](#operation-codes). Uma requisição que falha na validação de schema não traz `code`: ela responde `422` com o detail `validation failed`, ou `400` quando o corpo não pode ser interpretado, e a lista `errors` nomeia cada campo.
* **`errors`** – Lista opcional de detalhes de erro individuais, cada um com um `location`, um `message` e um `value`.
* **`instance`** – O trace ID da requisição, quando o gateway a rastreou. Informe-o ao reportar uma falha à Lerian.
* **`upstream`** – O erro que um sistema upstream retornou e que o gateway repassa. Ele vem do Dataprev nas operações do trilho, e do Streaming Hub nas operações de subscription. Ele contém o `code` e o `message` desse sistema, e sobrevive à sanitização de `5xx` que limpa o `detail`. Veja [Códigos de motivo do Dataprev](#dataprev-reason-codes).
* **`refusal`** – Em uma recusa de lance: o motivo que o gateway registrou para o lance, com `source`, `field`, `rule` e `detail`. Uma recusa do Dataprev também traz o `code` do Dataprev.
* **`existing_id`** – Em uma recusa `subscription_name_taken`, o id da subscription ativa no seu escopo que tem o nome.

## 400: Requisição inválida

***

| `code` | Descrição | `detail` |
| - | - | - |
| CLT-0001 | Requisição inválida. Por exemplo, uma requisição de credenciais informa um código de solicitante que não tem três dígitos, ou um certificado e uma chave que não formam um par PEM válido. Uma requisição com uma chave `X-Idempotency` mais longa do que a operação aceita também recebe esse código. Uma confirmação de desembolso, uma execução de garantia FGTS, uma correção de contrato e um comando que responde códigos `RAIL_COMMAND_*` respondem a uma chave longa demais com `422`. Uma importação de contrato com contabilização aceita uma chave de até 121 bytes: uma chave de 122 a 128 bytes responde `422` `CLT-0006`. Uma requisição que falha na validação de schema não carrega código. | — |
| CLT-0011 | Falha na requisição. O código de fallback para uma recusa do lado do cliente sem entrada própria. | Nomeia a recusa. |

## 401: Não autorizado

***

| `code` | Descrição | `detail` |
| - | - | - |
| CLT-0003 | Não autorizado. A requisição não trouxe um bearer token válido, ou o gateway não conseguiu resolver um tenant a partir dele. | `Unauthorized`, ou uma frase que nomeia a causa, como `The bearer token was not accepted.` |

## 403: Proibido

***

| `code` | Descrição | `detail` |
| - | - | - |
| CLT-0004 | Proibido. O chamador autenticado não tem permissão para esta operação. Um chamador que age por um originador ou por um fundo também recebe esse código em um contrato que pertence a outra parte. | `Forbidden` |
| AUT-1022 | Escopo de parceiro ambíguo. Uma credencial de parceiro originador chamou uma rota sem o id do originador no caminho (`/v1/consignado/originador` ou uma rota sob ele), e o escopo dela tem mais de um originador. | o parceiro desta credencial alcança mais de um valor de originador para este produto, e esta rota precisa de exatamente um; chame uma rota que nomeie o valor, ou restrinja o escopo do parceiro no Access Manager |

Um gateway cuja licença Lerian falhou recusa toda nova requisição com `403` enquanto é encerrado, exceto `/health`, `/readyz`, `/readyz/tenant/...`, `/version` e `/metrics`. Esse corpo não é problem details: é um JSON com `code`, `title` e `message`. Para os códigos dele, veja a [lista de erros do License Manager](https://docs.lerian.studio/pt/platform/licensing/license-manager-error-list.md). Em um deploy BYOC, verifique `LICENSE_KEY`.

## 404: Não encontrado

***

| `code` | Descrição | `detail` |
| - | - | - |
| CLT-0005 | Não encontrado. O registro nomeado pela requisição não existe para este tenant. Um artefato retido pertencente a outro tenant responde da mesma forma. | `Not Found`, `The requested resource was not found.`, ou uma frase que nomeia o que falta, como `contract is not an averbação of this tenant` |

Uma exclusão de um contrato que tem uma averbação contabilizada no gateway, mas saiu do registro, responde esse código com o detalhe `the gateway holds neither a booked averbação nor a live M015 obligation of this contract for this tenant`. Nada é enviado ao Dataprev.

## 409: Conflito

***

| `code` | Descrição | `detail` |
| - | - | - |
| CLT-0007 | Conflito. A requisição conflita com o estado atual do registro. | `Conflict`, ou a frase específica do conflito, como `an identical request is already in flight`. |

`CLT-0007` com o detail `an identical request is already in flight` marca uma requisição que o gateway ainda não terminou. Repita essa requisição sob a mesma chave de idempotência.

Conflitos de comando respondem com um código nomeado no lugar de `CLT-0007`, para que um cliente consiga diferenciá-los. Leia `code` e `detail` juntos antes de repetir a requisição. Essas grafias de código fazem parte do contrato de wire e não mudam.

| `code` | Descrição | `detail` |
| - | - | - |
| FGTS\_EXECUTION\_PAYLOAD\_MISMATCH | Esta chave de idempotência já contém uma execução de garantia FGTS diferente. | Esta chave de idempotência já contém uma execução de garantia FGTS diferente. Reenvie a requisição original sob esta chave para reproduzi-la, ou use uma nova chave para uma execução diferente. |
| FGTS\_EXECUTION\_OUTCOME\_UNRESOLVED | A execução mantida sob esta chave de idempotência ainda não tem um resultado conhecido, então ela não pode ser reproduzida. | A execução da garantia FGTS mantida sob esta chave de idempotência ainda não tem um resultado conhecido, então ela não pode ser reproduzida. Executar o mesmo contrato sob uma nova chave arrisca movimentar o dinheiro duas vezes. |
| FGTS\_EXECUTION\_ALREADY\_REFUSED | A execução mantida sob esta chave de idempotência foi recusada, então uma requisição corrigida precisa de uma nova chave. | A execução da garantia FGTS mantida sob esta chave de idempotência foi recusada. Esta chave apenas pode retornar essa recusa, então uma requisição corrigida precisa de uma nova chave. |
| FGTS\_EXECUTION\_CONTRACT\_TAKEN | A garantia FGTS deste contrato já foi executada sob outra chave de idempotência. Esta requisição não foi executada. | A garantia FGTS deste contrato já foi executada sob outra chave de idempotência, e uma garantia é executada uma única vez. Esta requisição não foi executada. |
| BID\_SOLICITACAO\_TAKEN | A solicitação já contém um lance desta instituição. | Esta solicitação já contém um lance desta instituição, e uma solicitação aceita apenas um. Consulte o livro de lances para o resultado do lance que a detém. |
| BID\_PROPOSAL\_SLOT\_TAKEN | Um envio anterior ocupa a posição da proposta, então este lance não foi registrado. | Uma posição de proposta neste lance já está ocupada por um envio anterior, então este lance não foi registrado. Consulte o livro de lances para o resultado do envio que a detém. |
| AVERBACAO\_CLAIM\_CONFLICT | A averbação deste contrato já está reivindicada sob outra chave de idempotência. | A averbação deste contrato já está reivindicada sob outra chave de idempotência. Acompanhe a reivindicação existente em vez de abrir uma segunda. |
| AVERBACAO\_ARTIFACT\_CONFLICT | Um documento diferente já está retido para a averbação deste contrato. Esta requisição não foi aplicada. | Um documento diferente já está retido para a averbação deste contrato, e um documento retido nunca é substituído. Esta requisição não foi aplicada. |
| AVERBACAO\_NOT\_ACCEPTED | A documentação exige uma averbação que o Dataprev aceitou, e este contrato não tem nenhuma. A recusa é definitiva apenas quando a averbação lê `rejected`. A credencial do tenant a lê em `GET .../averbacao`. Uma credencial de originador ou de fundo reenvia o mesmo corpo da averbação sob uma nova chave. | A documentação exige uma averbação aceita pelo Dataprev, e este contrato não tem nenhuma: consulte GET .../averbacao. Nada foi enviado ao Dataprev. |
| AVERBACAO\_DOCUMENTATION\_CONFLICT | Este contrato tem uma documentação que o Dataprev aceitou ou que está a caminho, ou a proposta de leilão dele já foi resolvida. Um contrato aceita uma única documentação aceita, e uma proposta resolvida não aceita nenhuma. | Este contrato tem uma documentação que o Dataprev aceitou ou que está a caminho (acompanhe a existente), ou a proposta de leilão dele já foi resolvida e nenhuma documentação é aceita para ele. Nada foi enviado ao Dataprev. |
| AVERBACAO\_EXCLUDED | Uma exclusão desta averbação foi solicitada, ou o contrato saiu do registro, então o gateway não aceita documentação para ela. Se o Dataprev rejeitar a exclusão, a mesma documentação passa. | Uma exclusão deste contrato foi solicitada e o Dataprev não a rejeitou (consulte GET .../exclusion), ou o contrato saiu do registro: um refinanciamento, uma renegociação ou uma exclusão por portabilidade registrados aqui o tiraram, ou o Dataprev o mostrou excluído ou encerrado fora deste gateway (consulte dataprev\_follow\_up em GET .../averbacao). Nenhuma documentação é aceita para ele, e nada foi enviado ao Dataprev. |
| AVERBACAO\_HELD\_BY\_ANOTHER\_SENDER | Uma credencial de outro tipo enviou esta mesma requisição primeiro, e ela não chegou ao Dataprev. Apenas uma credencial desse tipo pode retomá-la, enviando-a de novo. | Uma credencial de outra natureza (bancarizador, fundo ou originador) enviou esta mesma requisição primeiro e ela não chegou ao Dataprev: apenas uma credencial dessa natureza a retoma, enviando-a de novo. Nada foi enviado ao Dataprev. |
| EXCLUSION\_AUTHORITY\_CONFLICT | A exclusão deste contrato já está registrada sob outra autoridade. Esta requisição não foi aplicada. | A exclusão deste contrato já está registrada sob outra autoridade, e uma exclusão não tem desfazer. Esta requisição não foi aplicada. |
| EXCLUSION\_DOCUMENTATION\_UNDERWAY | Uma chamada de documentação ao Dataprev está em andamento para este contrato, então ele não está confirmado e não pode ser excluído agora. O mesmo vale para o novo contrato que uma renegociação criou, enquanto a chamada de documentação dele roda. Uma documentação que o gateway registrou mas ainda não enviou não bloqueia a exclusão: a exclusão a descarta. | A documentação deste contrato está a caminho do Dataprev, então ele ainda não está confirmado e não pode ser excluído agora. Envie a exclusão de novo quando GET /v1/consignado/averbacao-operations listar o contrato como confirmed ou attachment\_pending, ou quando o attachment\_invocation\_deadline\_at dele tiver passado. Nada foi enviado ao Dataprev. |
| EXCLUSION\_RENEGOTIATION\_UNDERWAY | Uma renegociação que substitui este contrato ainda não tem resposta do Dataprev, então o contrato não pode ser excluído agora. | A renegociação deste contrato ainda não foi respondida pelo Dataprev, então o contrato pode ser substituído e não pode ser excluído agora. Envie a exclusão de novo quando GET /v1/consignado/rail-commands mostrar a renegociação aceita ou rejeitada. Nada foi enviado ao Dataprev. |
| RENEGOTIATION\_EXCLUSION\_UNDERWAY | Uma exclusão do contrato encerrado foi solicitada e o Dataprev não a rejeitou, então a renegociação não pode ser enviada agora. | Uma exclusão do contrato encerrado foi solicitada e o Dataprev não a rejeitou (leia GET /v1/consignado/contracts/{numero_contrato}/exclusion), então ele não pode ser renegociado agora. Nada foi enviado ao Dataprev; envie a renegociação de novo apenas se essa exclusão terminar rejeitada. |
| EXCLUSION\_BOOKING\_IDENTITY\_INCOMPLETE | Os dados de contabilização que o gateway mantém para este contrato não têm a identidade do trabalhador ou do empregador que o Manual 003 exige. Nenhuma requisição pode corrigi-los: informe a Lerian com o `instance`. | O booking que o gateway mantém para este contrato não tem a identidade do trabalhador ou do empregador que o M003 exige, então a exclusão não pode ser enviada. Corrija o booking; nenhuma mudança nesta requisição pode ter sucesso. |
| RAIL\_COMMAND\_CLAIM\_CONFLICT | Este comando já está reivindicado para este contrato sob outra chave de idempotência. | Este comando já está reivindicado para este contrato sob outra chave de idempotência. Acompanhe a reivindicação existente em vez de abrir uma segunda. |
| RAIL\_COMMAND\_PAYLOAD\_MISMATCH | Esta chave de idempotência já contém um comando diferente para este contrato. | Esta chave de idempotência já contém um comando diferente para este contrato. Reenvie a requisição original sob esta chave para reproduzi-la, ou use uma nova chave para um comando diferente. |
| RAIL\_COMMAND\_ALREADY\_REFUSED | O comando mantido sob esta chave de idempotência foi recusado, pelo Dataprev ou antes de chegar ao Dataprev. Uma requisição corrigida precisa de uma nova chave. | O comando mantido sob esta chave de idempotência foi recusado, pelo Dataprev ou antes de chegar ao Dataprev. Esta chave apenas pode retornar essa recusa, então uma requisição corrigida precisa de uma nova chave. |
| RAIL\_COMMAND\_OUTCOME\_UNRESOLVED | O comando mantido sob esta chave de idempotência ainda não tem um resultado conhecido. Não o envie sob uma nova chave. | O comando mantido sob esta chave de idempotência ainda não tem um resultado conhecido, então ele não pode ser reproduzido. Consulte GET /v1/consignado/rail-commands; não o envie sob uma nova chave. |
| RAIL\_COMMAND\_ANSWER\_NOT\_RETAINED | Este comando já foi confirmado para este contrato, e sua resposta original não foi mantida. | Este comando já foi confirmado para este contrato, mas sua resposta original não foi mantida, então não há nada para reproduzir. Consulte o estado atual do contrato em vez de reenviá-lo. |
| RAIL\_COMMAND\_NOT\_CLOSEABLE | O banco não pode fechar este comando estacionado agora. O banco fecha apenas um refinanciamento, renegociação, alteração de termos ou renegociação de legado que esteja estacionada em `outcome_unknown`. | O banco fecha apenas um refinanciamento, renegociação, alteração de termos ou renegociação de legado estacionado em outcome\_unknown, uma vez. Este é de outro tipo, não está estacionado, foi estacionado há menos de cinco minutos, já está fechado com outra resposta, é uma alteração substituída ou sem termos declarados, ou está retido por outro contrato ativo até que a reversão desse contrato seja registrada. Leia GET /v1/consignado/rail-commands. |
| RAIL\_COMMAND\_CLOSE\_CONTRADICTED | A única leitura do contrato pelo Dataprev contradiz a declaração do banco de que o comando foi aceito. Nada foi gravado. | A leitura do contrato pelo Dataprev contradiz um fechamento como aceito: o contrato não existe, é outro, não está vigente, tem antecipações, ou carrega termos que o relatório de saldo devedor não comporta. Nada foi gravado; a operação Lerian decide. |
| REVERSAO\_WINDOW\_EXPIRED | A janela para estornar este refinanciamento se fechou, então nenhuma correção a reabre. | A janela para estornar este refinanciamento se fechou, então o estorno não pode mais ser solicitado. Nenhuma correção a esta requisição pode reabri-la. |
| DISBURSEMENT\_PAYMENT\_CONFLICT | Esta referência de pagamento já contém uma confirmação com outro valor ou outro horário de pagamento. Registre uma correção de desembolso para alterá-la. | Este payment\_reference já contém uma confirmação com amount ou paid\_at diferente, e uma confirmação é imutável. Registre uma correção de desembolso (correction\_type=disbursement) para alterá-la. |
| CONTRACT\_ALREADY\_REGISTERED | A importação de contrato nomeia um contrato que este tenant já possui: no livro de saldo devedor, para uma importação sem contabilização, ou no livro de averbações, para uma importação com contabilização. Uma averbação o responde quando o número do contrato dela já é um contrato neste gateway. Esse contrato veio de um refinanciamento, de uma renegociação, de uma importação ou de uma portabilidade. | Para uma importação, nomeia o livro que contém o contrato e o próximo passo: leia a obrigação que existe, ou reenvie a importação original para reproduzi-la. Para uma averbação: este número de contrato já é um contrato neste gateway, criado por um refinanciamento ou uma renegociação, importado, ou recebido por portabilidade. Ele não pode ser averbado de novo. Nada foi gravado e nada foi enviado ao Dataprev. |
| DATAPREV\_CREDENTIAL\_REQUIRED | O tenant não tem credencial do Dataprev em custódia, então nenhuma operação do trilho pode rodar para ele. | Este tenant não tem credencial do Dataprev em custódia, então o gateway não pode agir por ele no trilho. Provisione a credencial primeiro; nenhuma correção a esta requisição pode ter sucesso até lá. |
| DATAPREV\_CREDENTIAL\_REJECTED | O Dataprev recusou as credenciais de cliente OAuth do tenant. | O Dataprev recusou as credenciais de cliente OAuth deste tenant. Corrija-as na custódia de credenciais do gateway; repetir sem mudança não pode ter sucesso. |
| DATAPREV\_CREDENTIAL\_REVOKED | As credenciais do Dataprev do tenant foram revogadas. As operações do trilho respondem esse código, assim como os envios de certificado, de credenciais OAuth e de código de solicitante. Um envio completo que leva o certificado revogado, ou um segredo de cliente OAuth que uma revogação aposentou, também o responde. | As credenciais do Dataprev deste tenant foram revogadas, e o material revogado nunca é usado de novo. A custódia volta apenas por meio de um envio completo, o certificado e o cliente OAuth juntos: PUT /v1/credentials/dataprev com certPem, keyPem, clientId e clientSecret. Um segredo de cliente aposentado responde uma frase que manda gerar de novo o segredo no Dataprev. |

Após `DATAPREV_CREDENTIAL_REQUIRED`, envie o certificado Dataprev, as credenciais OAuth e o código de solicitante do tenant, e depois envie a requisição novamente. Após `DATAPREV_CREDENTIAL_REVOKED`, envie um novo certificado e um novo cliente OAuth juntos com [`PUT /v1/credentials/dataprev`](https://docs.lerian.studio/pt/reference/rails/consignado/put-dataprev-credentials). O client id pode continuar o mesmo, mas o segredo do cliente precisa ser gerado de novo no Dataprev. Após `DATAPREV_CREDENTIAL_REJECTED`, corrija as credenciais de cliente OAuth do tenant e depois envie uma leitura novamente. Uma escrita pode ter deixado o comando parado: veja [Opere o Lerian Consignado](https://docs.lerian.studio/pt/rails/consignado/consignado-operations.md#credentials-and-artifacts) antes de enviá-la novamente.

## 410: Removido

***

A varredura paginada de inventário de registros emite um cursor com uma janela limitada de repetição.

| `code` | Descrição | `detail` |
| - | - | - |
| CURSOR\_EXPIRED | Removido. A janela de repetição do cursor expirou, então a varredura à qual ele pertencia não pode continuar. Inicie uma nova varredura. | A janela de repetição do cursor expirou. |

## 413: Entidade da requisição muito grande

***

| `code` | Descrição | `detail` |
| - | - | - |
| CLT-0010 | Entidade da requisição muito grande. O payload da requisição é maior do que o endpoint aceita, ou o corpo de um comando contém mais tokens JSON do que o comando aceita. | Nomeia o limite que a requisição ultrapassou, em bytes ou em tokens JSON. |

Um corpo de averbação que traz a CCB assinada, o pacote de evidências, a evidência de assinatura ou `data_hora_assinatura` é recusado. Ele responde `413` com 1 MiB ou mais, e `422` com o detail `validation failed` abaixo disso. Envie-os para `POST /v1/consignado/contracts/{numero_contrato}/ccb-attachment` depois que o Dataprev aceitar a averbação.

## 422: Entidade não processável

***

| `code` | Descrição | `detail` |
| - | - | - |
| CLT-0006 | Entidade não processável. O gateway leu a requisição e a recusa em sua forma atual. Uma rejeição determinística do Dataprev também responde aqui, e traz `upstream`. | O motivo para agir, como obter uma nova autorização do trabalhador. |

Algumas recusas respondem com um código nomeado no lugar de `CLT-0006`. Nada chegou ao Dataprev. A descrição diz o que fazer em seguida.

| `code` | Descrição | `detail` |
| - | - | - |
| IDEMPOTENCY\_KEY\_REUSE | A chave `X-Idempotency` já foi consumida por uma requisição diferente. Envie a requisição alterada sob uma nova chave. | A chave X-Idempotency já foi usada com uma requisição diferente; envie uma nova chave para uma requisição alterada. |
| FUNDO\_NOT\_REGISTERED | `fundo_ref` não nomeia um fundo registrado para este tenant. Corrija `fundo_ref`. | fundo\_ref não nomeia um fundo registrado para este tenant |
| FUNDO\_DEACTIVATED | O fundo que `fundo_ref` nomeia não aceita mais crédito novo. | o fundo nomeado está desativado e não aceita crédito novo |
| FIRST\_DEDUCTION\_BEFORE\_COMPETENCIA | `data_primeiro_desconto` cai em um mês anterior a `first_deduction_competencia`. Corrija as datas. | Nomeia a regra. |
| DECLARED\_DATES\_OUT\_OF\_ORDER | As datas declaradas quebram uma ordem que a contabilização exige. Corrija as datas. | Nomeia a regra. |
| FORMALIZATION\_DEADLINE\_EXCEEDED | `data_hora_assinatura` é posterior a `formalization_deadline`. Quando a documentação responder esse código, exclua a averbação e depois formalize o contrato novamente. | Nomeia a regra. |
| BOOKING\_FIELD\_INVALID | O Lender não consegue ler um campo do bloco de contabilização. | Nomeia o campo. |
| DECLARED\_TERMS\_INCONSISTENT | Os valores ou as taxas declarados se contradizem. Corrija os termos. | Nomeia a regra. |
| MARGIN\_SNAPSHOT\_INCONSISTENT | `margin_snapshot` não comporta `installment_amount`. Leia a margem de novo ou precifique o contrato de novo. | Nomeia a regra. |
| CONTRACT\_NOT\_BOOKABLE | O Lender não consegue contabilizar este contrato de forma alguma. Envie a requisição sem o bloco de contabilização. | Nomeia a regra. |
| RATE\_OUTSIDE\_PRODUCT\_RANGE | `monthly_rate` vezes 12 fica fora da faixa de taxa anual da versão de produto do Lender que `loan_product_version` nomeia. | Nomeia a faixa. |
| LOAN\_PRODUCT\_VERSION\_UNKNOWN | `loan_product_version` nomeia uma versão que o gateway não recebeu do Lender. Uma versão criada há instantes pode ainda estar a caminho, então envie a requisição de novo mais tarde. Uma versão criada antes de o gateway ser vinculado ao tenant nunca chega: crie uma nova versão no Lender. Um tenant sem versão do Lender não é verificado. | Nomeia a regra. |
| VERSION\_ADMITS\_NO\_PESSOA\_FISICA | O Lender publicou a versão que `loan_product_version` nomeia como uma versão que não admite `pessoaFisica`. Uma versão publicada sem os tipos de tomador admitidos não é verificada. | Nomeia a regra. |
| MATRICULA\_DIFFERS\_FROM\_PROPOSAL | A `matricula` da averbação difere daquela para a qual o `numero_proposta` dela foi vencido. Corrija a `matricula`. Uma proposta que o gateway não tem, ou uma guardada sem `matricula`, passa. | Nomeia a regra. |
| BID\_ORIGINADOR\_UNKNOWN | O originador para o qual o lance é feito não está registrado para este tenant. | O originador para o qual este lance é feito não está registrado para este tenant. Um bancarizador o nomeia em originadorRef; uma credencial de originador faz lances sob sua própria referência, que precisa estar registrada antes de fazer lances. |
| BID\_ORIGINADOR\_INACTIVE | O originador para o qual o lance é feito não pode mais agir por este tenant. | O originador para o qual este lance é feito pode não agir mais por este tenant. Um bancarizador o nomeia em originadorRef; uma credencial de originador faz lances sob sua própria referência, que precisa ser reativada antes de fazer lances de novo. |
| BID\_SOLICITACAO\_UNKNOWN | O gateway não mantém nenhuma solicitação descoberta sob este identificador. Tente de novo depois que o evento `consignado.solicitacao.received` dela chegar. | O gateway não mantém nenhuma solicitação descoberta sob este identificador. Tente de novo depois que o evento consignado\_solicitacao.received dela chegar; nada foi registrado. |
| BID\_NO\_PROPOSTA\_LEFT | Um lance retomado não tem mais proposta para enviar de novo. Faça um novo lance. | Não resta proposta para repetir sob esta chave de idempotência: ou a validadeProposta dela passou e o Dataprev não a aceita mais, ou o payload armazenado já foi apagado pela retenção deste serviço. Faça um novo lance se a solicitação ainda estiver aberta. |
| PORTABILIDADE\_WINDOW\_EXPIRED | A janela da portabilidade passou: os 20 dias corridos para concluir uma portabilidade de saída, ou a validade da solicitação que uma resposta ao leilão de portabilidade responde. | Nomeia a janela. |

Os códigos de contabilização, de `FIRST_DEDUCTION_BEFORE_COMPETENCIA` a `VERSION_ADMITS_NO_PESSOA_FISICA`, valem apenas para uma requisição enviada com o bloco de contabilização. O gateway verifica a versão nesta ordem: `LOAN_PRODUCT_VERSION_UNKNOWN`, `VERSION_ADMITS_NO_PESSOA_FISICA` e depois `RATE_OUTSIDE_PRODUCT_RANGE`. `MATRICULA_DIFFERS_FROM_PROPOSAL` vale para uma averbação com ou sem o bloco de contabilização.

Cada superfície responde estes códigos de contabilização:

* Uma averbação: todos os códigos de contabilização, exceto `FORMALIZATION_DEADLINE_EXCEEDED`.
* A documentação de uma averbação: apenas `DECLARED_DATES_OUT_OF_ORDER` e `FORMALIZATION_DEADLINE_EXCEEDED`.
* Uma importação de contrato com `booking`: todos os códigos de contabilização, exceto `FIRST_DEDUCTION_BEFORE_COMPETENCIA`.
* Um refinanciamento com `booking`: todos os códigos de contabilização, exceto `FORMALIZATION_DEADLINE_EXCEEDED`.
* Uma averbação de portabilidade com `booking`: todos os códigos de contabilização, exceto `FIRST_DEDUCTION_BEFORE_COMPETENCIA` e `FORMALIZATION_DEADLINE_EXCEEDED`.

Um comando enviado novamente com uma chave de idempotência que uma requisição anterior já consumiu pode responder um de quatro códigos nomeados. A requisição anterior pode já ter chegado ao Dataprev. Não envie o comando novamente, nem com esta chave nem com uma nova. Leia o estado atual do registro que o comando altera. A [resposta ao leilão de portabilidade](https://docs.lerian.studio/pt/reference/rails/consignado/respond-consignado-portability-auction.md) é a exceção: a referência dela explica como um reenvio com uma nova chave revela o resultado.

| `code` | Descrição | `detail` |
| - | - | - |
| IDEMPOTENCY\_STATE\_UNRECOGNISED | O registro mantido sob esta chave foi gravado por uma versão mais nova do serviço. | Uma requisição anterior consumiu esta chave de idempotência com um registro gravado por uma versão mais nova deste serviço; concilie a requisição original e não tente de novo com uma nova chave. |
| IDEMPOTENCY\_RECORD\_UNREADABLE | O registro mantido sob esta chave não pode ser lido. | Uma requisição anterior consumiu esta chave de idempotência com um registro que este serviço não consegue ler; concilie a requisição original e não tente de novo com uma nova chave. |
| IDEMPOTENCY\_OUTCOME\_UNRECORDED | A requisição anterior sob esta chave não tem desfecho registrado. | Uma requisição anterior consumiu esta chave de idempotência e seu desfecho não foi registrado; concilie a requisição original e não tente de novo com uma nova chave. |
| IDEMPOTENCY\_REPLAY\_UNAVAILABLE | A requisição anterior sob esta chave foi concluída, e sua resposta não pode ser reproduzida. | Uma requisição anterior com esta chave de idempotência foi concluída e sua resposta foi entregue uma vez, mas não pode ser reproduzida; não reenvie, concilie o recurso que o comando altera e não tente de novo com uma nova chave. |

## 429: Muitas requisições

***

| `code` | Descrição | `detail` |
| - | - | - |
| CLT-0009 | Muitas requisições. O chamador excedeu seu orçamento de requisições. | `Too many requests were sent in a given amount of time.` |

Aguarde o tempo indicado no header `Retry-After` e depois envie a requisição novamente.

## 500: Erro interno do servidor

***

| `code` | Descrição | `detail` |
| - | - | - |
| CLT-0002 | Erro interno do servidor. Uma falha inesperada dentro do gateway. Uma alteração de subscrição que o Streaming Hub pode ter efetivado sem registrar o desfecho também responde esse código, com `upstream.code` `idempotency_outcome_unrecorded`. Leia a subscrição antes de enviar a alteração de novo, com esta chave ou com uma nova. | `internal error` |

## 501: Não implementado

***

Um `501` responde a uma operação que seu deploy não habilitou. As rotas permanecem montadas, então a resposta chega por requisição, em vez de como um path ausente. Estas operações respondem `501` até que seu deploy as habilite:

* downloads de artefato de contrato
* correções de contrato
* envio de lance
* operações que chegam ao Dataprev

A revogação de credenciais do Dataprev responde `501` em um deploy cujas credenciais são estáticas.

O `detail` traz `internal error`, porque o Consignado sanitiza o detail em uma resposta `5xx`. A revogação de credenciais é a exceção: o detail dela diz que as credenciais são estáticas. Baseie sua lógica no status.

## 502: Gateway inválido

***

| `code` | Descrição | `detail` |
| - | - | - |
| DATAPREV\_INVALID\_RESPONSE | O Dataprev retornou, para uma leitura, dados que o gateway não consegue usar. Nada mudou. Tente de novo mais tarde, ou estreite a janela da leitura. | O Dataprev retornou dados para esta leitura que o gateway não conseguiu usar; nada foi alterado. Tente de novo mais tarde ou estreite a janela, citando este instance se o problema persistir. |

## 503: Serviço indisponível

***

| `code` | Descrição | `detail` |
| - | - | - |
| CLT-0008 | Serviço indisponível. O gateway não consegue atender a requisição agora. O armazenamento próprio ou a custódia de credenciais dele está indisponível, ou o controle de ritmo das chamadas ao Dataprev segurou a requisição além do prazo dela. Envie a mesma requisição novamente em breve, sob a mesma chave de idempotência. | Uma frase que nomeia a causa, ou `internal error`. |
| DATAPREV\_UNAVAILABLE | O Dataprev respondeu com uma falha de repetir-mais-tarde, ou não respondeu. Tente de novo mais tarde sob a mesma chave de idempotência. Quando o detalhe diz que o gateway fechou o comando como recusado, nada foi executado no Dataprev: envie o comando de novo sob uma nova chave. | O Dataprev está indisponível para esta requisição agora; o membro upstream traz o código próprio dele quando ele enviou um. Tente de novo mais tarde, reutilizando a mesma chave X-Idempotency em um comando. |
| OUTCOME\_UNKNOWN | O gateway não sabe se a requisição teve efeito. Ele não conseguiu registrar o desfecho, a confirmação de um lance pelo Dataprev foi ambígua, ou a resposta do Dataprev a um comando do trilho não o decidiu. Repita apenas sob a mesma chave de idempotência, exceto em um comando do trilho e em uma averbação de portabilidade cujo detalhe diz que ela não foi enviada de novo. | O gateway não conseguiu registrar o desfecho desta requisição, então não se sabe se ela teve efeito. Nunca a reenvie sob uma nova chave: repita sob a MESMA chave X-Idempotency e, se essa repetição responder IDEMPOTENCY\_OUTCOME\_UNRECORDED, concilie a requisição original. |
| STREAMING\_HUB\_UNAVAILABLE | O Streaming Hub por trás das operações de subscription está indisponível. | O streaming hub está indisponível. Tente de novo mais tarde, reutilizando a mesma chave X-Idempotency em uma alteração. |
| TENANT\_MANAGER\_UNAVAILABLE | O Tenant Manager está indisponível, então o gateway não consegue resolver seu tenant. Apenas um deploy multi-tenant responde esse código. | o tenant manager está indisponível; repita a requisição mais tarde |
| AUT-0033 | O Access Manager não decidiu sobre esta requisição. | O Access Manager não decidiu esta requisição. Aguarde um momento e tente de novo. |

Uma resposta `DATAPREV_UNAVAILABLE`, `DATAPREV_TIMEOUT` ou `OUTCOME_UNKNOWN` também traz `upstream` quando o Dataprev enviou o código e a mensagem próprios.

Um comando do trilho que responde `OUTCOME_UNKNOWN` está estacionado. O Dataprev respondeu com um código que não é recusa nem aceite, não respondeu a tempo, ou respondeu sem o envelope. Não o envie de novo, nem com uma nova chave nem com a mesma, porque a mesma chave responde `RAIL_COMMAND_OUTCOME_UNRESOLVED`. Leia `GET /v1/consignado/rail-commands` para ver o desfecho. Uma suspensão, reativação, ou inclusão ou exclusão de legado estacionada continua em `outcome_unknown`: confirme o efeito dela no portal do Dataprev.

Uma averbação de portabilidade o responde enquanto o gateway decide o contrato no Dataprev. Reenviar com qualquer chave é seguro, e nada chega de novo ao Dataprev até o desfecho se decidir.

## 504: Timeout do gateway

***

| `code` | Descrição | `detail` |
| - | - | - |
| DATAPREV\_TIMEOUT | O Dataprev não respondeu a tempo. Se a requisição altera estado no Dataprev, o desfecho dela é desconhecido. Repita apenas sob a mesma chave de idempotência. Um comando do trilho não responde esse código: responde `OUTCOME_UNKNOWN`. | O Dataprev não respondeu a tempo, então, se esta requisição altera estado no Dataprev, o desfecho dela é desconhecido. Nunca a reenvie sob uma nova chave: repita sob a MESMA chave X-Idempotency e, se essa repetição responder IDEMPOTENCY\_OUTCOME\_UNRECORDED, concilie a requisição original. |
| STREAMING\_HUB\_TIMEOUT | O Streaming Hub por trás das operações de subscription não respondeu a tempo. | O streaming hub não respondeu a tempo. Tente de novo, reutilizando a mesma chave X-Idempotency em uma alteração. |
| TENANT\_MANAGER\_TIMEOUT | O Tenant Manager não respondeu a tempo. Apenas um deploy multi-tenant responde esse código. | o tenant manager não respondeu a tempo; repita a requisição |
| AUT-1021 | O Access Manager não respondeu a tempo. | O Access Manager não respondeu a tempo. Tente de novo. |

## Códigos por operação

***

Algumas operações respondem com códigos próprios, nomeados a partir da operação: `FUNDO_*`, `ORIGINADOR_*`, `CEDED_CREDIT_*`, `SALDO_DEVEDOR_*`, `REGISTRO_B3_*`, `HELD_REPASSE_*`, e os códigos de cursor e de filtro das operações de listagem. A referência da API enumera todos os códigos no campo `code` do schema de erro.

As operações do código de instrumento B3, `GET` e `PATCH /v1/consignado/contracts/{numero_contrato}/registro-b3`, respondem com estes códigos.

| `code` | Status | Descrição | `detail` |
| - | - | - | - |
| REGISTRO\_B3\_CONTRATO\_NAO\_ENCONTRADO | 404 | Este tenant não tem contrato com este número, ou o Dataprev recusou a averbação dele. No GET, uma averbação ainda sem resposta do Dataprev também responde este código. | Nenhum contrato assim foi encontrado para este tenant. |
| REGISTRO\_B3\_NAO\_INFORMADO | 404 | O Dataprev aceitou a averbação do contrato, e o contrato ainda não tem código de instrumento B3. | O contrato ainda não tem registro B3. |
| REGISTRO\_B3\_AVERBACAO\_NAO\_CONFIRMADA | 409 | A averbação do contrato ainda está em andamento, ou foi aceita mas não confirmada. O gateway aceita o código apenas depois que a averbação é confirmada. | A averbação do contrato não está confirmada. |
| REGISTRO\_B3\_JA\_INFORMADO | 409 | O contrato já tem outro código ou outra data de registro. A API não oferece correção. Enviar o mesmo registro de novo responde `200`. Um registro diferente responde esse código mesmo que a data dele fosse inválida. | O contrato já tem um registro B3 diferente. |
| REGISTRO\_B3\_DATA\_REGISTRO\_INVALIDA | 422 | `dataRegistro` está no futuro ou antes da averbação. O gateway só a verifica enquanto o contrato não tem código. | dataRegistro não pode estar no futuro nem antes da averbação. |
| REGISTRO\_B3\_INTERNAL | 500 | Uma falha inesperada. | `internal error` |
| REGISTRO\_B3\_UNWIRED | 501 | Este deploy não registra o código de instrumento B3. | `internal error` |
| REGISTRO\_B3\_UNAVAILABLE | 503 | O armazenamento do código de instrumento B3 está indisponível. Envie a requisição novamente em breve. | `internal error` |

A liberação de repasse retido, `POST /v1/consignado/reconciliation/held-repasses/{id}/release`, responde estes códigos. Em todo `409`, o repasse continua retido no painel.

| `code` | Status | Descrição | `detail` |
| - | - | - | - |
| HELD\_REPASSE\_NOT\_FOUND | 404 | Nenhum repasse retido tem este id, ou ele já foi liberado. | Este tenant não tem repasse retido com este id. |
| HELD\_REPASSE\_UNATTRIBUTABLE | 409 | Nenhuma expectativa daquela competência informa o empregador do repasse. | Nenhuma promessa daquele mês informa o empregador deste repasse: não existe nenhuma para este contrato, ou nenhuma nomeia o empregador. O repasse continua retido no painel. |
| HELD\_REPASSE\_MONTH\_MISMATCH | 409 | O repasse tem competência própria, e apenas essa competência o libera. | Este repasse tem mês próprio (o do trilho, ou o mês anterior ao pagamento da guia, horário de Brasília), e apenas esse mês o libera. O repasse continua retido no painel. |
| HELD\_REPASSE\_MONTH\_CLOSED | 409 | Outro repasse já fechou a expectativa daquela competência. | Outro repasse já fechou a promessa daquele mês e este não foi registrado nela. O repasse continua retido no painel. |

## Códigos de motivo do Dataprev

***

O Consignado repassa os códigos de motivo do Dataprev, em vez de mapeá-los para códigos próprios. Isso mantém uma recusa legível em relação ao que o Dataprev disse. Leia cada código de motivo em relação à especificação do Dataprev, não a esta página. O Dataprev pode publicar um código que esta página não lista, e o gateway ainda assim o entrega a você.

Eles chegam até você em três lugares.

**Em uma recusa.** O membro `upstream` traz o `code` e o `message` do próprio Dataprev. Uma recusa com vários códigos os lista separados por vírgula. O membro contém os códigos e as frases do Dataprev, com tamanho limitado, e não um corpo de resposta. Um `422` o traz para uma rejeição determinística. `DATAPREV_UNAVAILABLE` e `DATAPREV_TIMEOUT` o trazem para uma falha de repetir-mais-tarde, e `OUTCOME_UNKNOWN` o traz para um comando do trilho estacionado.

Uma recusa do Dataprev a um comando em `upstream` fica retida sob a chave de idempotência dele. Um `refusal` de lance também, qualquer que seja o `source` dele. A mesma chave retorna a mesma recusa, então envie uma requisição corrigida sob uma nova chave. Um lance recusado com `source` `dataprev` também retém a solicitação, então qualquer novo lance para essa solicitação responde `BID_SOLICITACAO_TAKEN`.

Uma recusa que o gateway faz por conta própria, sem `upstream` e sem membro `refusal` de lance, não retém a chave, então uma requisição corrigida pode ir sob a mesma chave. Uma execução de garantia FGTS e um comando que responde códigos `RAIL_COMMAND_*` são a exceção: eles retêm a chave desde antes de chamar o Dataprev. Quando um reenvio responde que uma requisição anterior já detém a chave, como `IDEMPOTENCY_KEY_REUSE` ou `RAIL_COMMAND_PAYLOAD_MISMATCH`, siga a instrução desse código.

**Em respostas de contrato e margem.** Vários campos de resposta emparelham um código de motivo do Dataprev com o rótulo próprio do Dataprev para ele. Uma leitura de margem publica `blockType` e `ineligibilityReason`, que formam o par `code` e `description`. Uma leitura de contrato publica `motivo_exclusao`, `origem_averbacao`, `origem_exclusao`, `portabilidade_situacao` e `situacao_bloqueio_garantia`, que formam o par `codigo` e `descricao`. Cada campo contém um código numérico e o texto que o Dataprev retornou ao lado dele.

**Em um comando do trilho.** O `response_code` de um comando em `GET /v1/consignado/rail-commands` também traz códigos que o próprio gateway grava, e eles começam com `GW-`. Os códigos de recusa abaixo chegam também ao `reason_code` dos fatos de recusa.

* `GW-NAO-ENVIADO`: a chamada não saiu do gateway, então nada foi executado no Dataprev. O comando fecha como recusado. Envie-o de novo sob uma nova chave.
* `GW-BANCO-RECUSADO`: o banco fechou o comando estacionado como recusado, conforme o que o portal do Dataprev mostra.
* `GW-M005-NAO-EXECUTADO`: uma leitura do contrato no Dataprev mostra que o comando não foi executado.

Os demais valores `GW-` marcam um comando que o gateway ou o banco fechou como aceito.

Trate o conjunto como aberto. Mapeie os códigos de motivo sobre os quais sua integração age, e repasse o restante com seus rótulos, para que um código ainda não mapeado continue legível para um operador.


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