> ## 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/`.
* **`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. Baseie sua lógica em `code` e no status.
* **`code`** – Um identificador estável para o erro. As tabelas abaixo listam os códigos `CLT-NNNN`. Algumas operações respondem com um código nomeado próprio, como `CURSOR_EXPIRED` na varredura de inventário de registros.
* **`errors`** – Lista opcional de detalhes de erro individuais, cada um com um `location`, um `message` e um `value`.
* **`upstream`** – O próprio erro do Dataprev, quando o gateway repassa um. Ele contém o `code` e o `message` do Dataprev, e sobrevive à sanitização de `5xx` que limpa o `detail`. Veja [Códigos de motivo do Dataprev](#dataprev-reason-codes).
## 400: Requisição inválida
***
| `code` | Descrição | `detail` |
| -------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| CLT-0001 | Requisição inválida. O gateway não conseguiu interpretar a sintaxe da requisição, ou um campo informado falhou na validação. | Nomeia o campo ou a sintaxe que o gateway recusou. |
| 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` |
## 403: Proibido
***
| `code` | Descrição | `detail` |
| -------- | ---------------------------------------------------------------------- | ----------- |
| CLT-0004 | Proibido. O chamador autenticado não tem permissão para esta operação. | `Forbidden` |
## 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` |
## 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. |
| EXCLUSION\_AUTHORITY\_QUARANTINED | Este contrato contém um registro de exclusão que o gateway não pode reportar, então ele não responde como ausente. | Este contrato contém um registro de exclusão que o gateway não pode reportar. Ele deliberadamente não é respondido como ausente, porque o contrato pode muito bem estar excluído. |
| 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. |
| 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\_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. |
| 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. |
## 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. | `Request Entity Too Large` |
## 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. |
## 500: Erro interno do servidor
***
| `code` | Descrição | `detail` |
| -------- | ----------------------------------------------------------------- | ---------------- |
| CLT-0002 | Erro interno do servidor. Uma falha inesperada dentro do gateway. | `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. Downloads de artefato de contrato, correções de contrato, confirmação de desembolso, registro de cessão e envio de lance respondem `501` até que seu deploy os habilite.
O `detail` traz `internal error`, porque o Consignado sanitiza o detail em uma resposta `5xx`. Baseie sua lógica no status.
## 503: Serviço indisponível
***
| `code` | Descrição | `detail` |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| CLT-0008 | Serviço indisponível. Uma dependência que a requisição precisa está indisponível, ou o Dataprev respondeu com uma falha de repetir-mais-tarde. Envie a mesma requisição novamente em breve. | `internal error` |
Quando o Dataprev produziu a falha, a resposta também traz `upstream` com o código e a mensagem do próprio Dataprev.
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 de fato 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 dois lugares.
**Em uma recusa.** O membro `upstream` traz o `code` e o `message` do próprio Dataprev, ambos literais. O gateway limita cada campo no wire, então o membro contém um código e uma frase, e não um corpo de resposta completo. Um `422` o traz para uma rejeição determinística, e um `503` o traz para uma falha de repetir-mais-tarde.
**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.
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.