> ## 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 TED Lerian

> O **TED Lerian** retorna respostas de erro estruturadas com um código estável, para que você identifique o que deu errado e como corrigir.

**Formato do erro**

Cada erro é um body `application/problem+json` (RFC 9457) com um `code` estável. Trate os erros pelo `code`; o texto de `detail` pode mudar.

```json JSON theme={null}
{
  "type": "https://errors.lerian.studio/v1/TED-0030",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "the transfer exceeds an institutional usage limit: DAILY usage limit exceeded",
  "code": "TED-0030",
  "fields": {"limit": "DAILY"}
}
```

**Definições de campo**

* **`code`** – Um identificador estável do erro, no formato `TED-NNNN`.
* **`title`** – Um resumo curto do tipo de problema.
* **`status`** – O código de status HTTP.
* **`detail`** – Uma explicação legível desta ocorrência.
* **`type`** – Uma referência ao tipo de problema: `https://errors.lerian.studio/v1/` seguido do `code`.
* **`instance`** – Opcional. Uma referência a esta ocorrência.
* **`errors`** – Opcional. Uma entrada para cada campo rejeitado, com `location`, `message` e `value`.
* **`fields`** – Opcional. Fatos para decidir. No `TED-0030`, `fields.limit` é `PER_TRANSACTION`, `DAILY` ou `MONTHLY`.
* **`upstream`** – Opcional. O erro que um provedor intermediado reportou, com o seu próprio `code` e `message`, literalmente.

Cada resposta, de sucesso ou de erro, traz o header `X-Request-Id`. Inclua-o nas solicitações de suporte.

## Erros do TED Lerian

***

Os erros a seguir podem ocorrer quando você chama os endpoints do TED Lerian. `TED-0031` e `TED-1013` nunca são respostas de erro: eles chegam em `rejection.code` de uma transferência com status `REJECTED`. Em um envio, `TED-1001`, `TED-1010` e `TED-1011` chegam da mesma forma. Se você repetir um `POST /v1/transfers` cuja primeira tentativa ficou sem resposta, qualquer recusa ainda pode significar que a primeira tentativa criou a transferência: consulte-a com `GET /v1/transfers` antes de enviá-la com uma chave nova.

| Código | HTTP | Título | Quando acontece | Como corrigir |
| - | - | - | - | - |
| `TED-0001` | 400 | Bad Request | O JSON está malformado ou um tipo é inválido. | Corrija o body da requisição. |
| `TED-0002` | 422 | Validation Failed | Um campo obrigatório está ausente, fora do formato ou fora do schema declarado (veja `errors`). No `PUT /v1/policy/ispb-bindings`, também um vínculo cuja configuração de TED está incompleta, uma lista vazia ou `null`, e o mesmo ISPB vinculado duas vezes à mesma organização e ao mesmo ledger. | Corrija os campos listados, ou crie o que a mensagem indica. |
| `TED-0003` | 422 | Invalid Purpose Code | `purposeCode` é desconhecido, ou não está vigente na data da requisição, no Dicionário de Domínios FinlddCli do BACEN. | Use um código ativo de 5 dígitos desse dicionário. |
| `TED-0004` | 422 | Description Required | `purposeCode=99999` sem `description`. | Envie `description`. |
| `TED-0005` | 422 | Recipient Bank Required | Nem `bankId` nem `bankCode` foi enviado, ou os dois foram. | Envie exatamente um. |
| `TED-0006` | 422 | Unknown Participant | `bankCode` ou `bankId` não está na relação de participantes do STR. | Verifique com `GET /v1/participants`. |
| `TED-0007` | 422 | Document Mismatch | Os dígitos verificadores do CPF ou CNPJ do recebedor não são válidos. | Corrija o documento. |
| `TED-0008` | 400 | Account Header Required | `X-Account-Id` está ausente ou não é um UUID. | Envie `X-Account-Id` com a conta de origem. |
| `TED-0009` | 403 | Account Not Owned | `X-Account-Id` não pertence à organização da identidade autenticada. | Use uma conta da sua própria organização. |
| `TED-0010` | 404 | Not Found | O recurso não existe na instituição. | Verifique o identificador. |
| `TED-0011` | 400 | Idempotency Key Required | `X-Idempotency` está ausente em uma requisição com efeito. | Envie o header. |
| `TED-0012` | 422 | Idempotency Key Reuse | A mesma chave com uma requisição diferente, `metadata` incluído. No `POST /v1/transfers`, também depois do `X-TTL`. | Um recurso já pode existir para essa chave. Consulte-o antes de usar uma chave nova (para uma transferência, `GET /v1/transfers` filtrado por `client_reference`, ou por `account_id` e data). |
| `TED-0013` | 409 | Idempotent Request In Flight | Uma requisição com a mesma chave ainda está em andamento. | Tente de novo após `Retry-After`. |
| `TED-0014` | 409 | Duplicate Request | Uma requisição materialmente idêntica com uma chave nova, enviada pouco depois de outra. | Leia a transferência existente. Para repetir uma requisição, envie a mesma chave. |
| `TED-0015` | 409 | Reconciliation Already Running | Um ciclo de conciliação já está em execução. | Aguarde o ciclo em execução terminar. |
| `TED-0020` | 422 | Outside Operating Window | Fora do horário oficial ou depois do cut-off da instituição. | Envie de novo na próxima janela (`GET /v1/policy/window`). |
| `TED-0021` | 422 | Non-Business Day | Fim de semana ou feriado bancário. | Envie de novo no próximo dia útil. |
| `TED-0022` | 503 | Operating Window Undetermined | A grade horária ou a configuração está indisponível, ou o calendário de feriados do ano da data não está carregado. Duas causas têm `detail` próprio: o STR não publicou a grade de transferências de clientes para a data, e não foi possível ler a grade do STR no trilho. O TED Lerian recusa em vez de adivinhar. | Se o ano não tem calendário de feriados, carregue-o com `PUT /v1/policy/holidays`. Se o STR não publicou a grade da data, tentar de novo não resolve para uma data passada. Se a grade não pôde ser lida no trilho, tente de novo mais tarde; se persistir, a conexão da instituição com o trilho precisa de atenção. Caso contrário, tente de novo. |
| `TED-0030` | 422 | Usage Limit Exceeded | O limite por transferência, diário ou mensal foi excedido. `fields.limit` indica qual. | Reduza o valor ou aguarde a virada do período. |
| `TED-0031` | — | Insufficient Balance | A conta de origem não tem saldo suficiente. | Ajuste o valor. |
| `TED-0040` | 503 | Fee Calculation Unavailable | O TED Lerian não consegue determinar a tarifa. O `detail` indica uma de três causas: o pacote de `fee.package_id` não existe no ledger; mais de um pacote de tarifas igualmente específico se aplica; ou o ledger está indisponível. | Na primeira causa, corrija `fee.package_id` ou limpe-o. Na segunda, restrinja os pacotes de tarifas para que exatamente um se aplique. Na terceira, tente de novo mais tarde. |
| `TED-0060` | 409 | Invalid State Transition | A ação não combina com o status atual, ou já foi aplicada (uma devolução ou uma decisão de revisão). | Leia o status e escolha a ação certa. |
| `TED-0061` | 409 | Not Cancellable | A transferência está liquidada, é recebida, já está em status final, ou está aguardando conciliação ou esgotada (o status real é desconhecido). | Use uma devolução quando ela se aplicar; para aguardando conciliação ou esgotada, use `POST /v1/transfers/{transferId}/unblock` com evidência. |
| `TED-0062` | 409 | Not Returnable | O status não permite uma devolução. | — |
| `TED-0063` | 422 | Partial Return Not Allowed | Um valor parcial foi enviado. | As devoluções são sempre integrais. |
| `TED-0064` | 422 | Invalid Return Code | `returnCode` está fora do domínio oficial. | Use um `CodDevTransf` válido. |
| `TED-0065` | 422 | Evidence Required | Um destravamento sem evidência válida, ou sem `rejectionCode` quando `outcome=REJECTED`. | Envie a evidência do STR (e o código de rejeição quando ele se aplicar). |
| `TED-0066` | 422 | Return Code Required | Uma resolução de revisão manual com `action=RETURN` e sem `returnCode`. | Envie `returnCode`. |
| `TED-0067` | 409 | Held Return Carried By Transfer | Uma transferência que ainda pode liquidar carrega a devolução retida que você tentou encerrar. | Não a encerre: o TED Lerian devolve o valor ao remetente quando essa transferência liquidar. Estorne qualquer crédito que você fez no ledger para ela. |
| `TED-0070` | 401 | Unauthorized | O token está ausente, inválido ou expirado. | Autentique-se. |
| `TED-0071` | 403 | Forbidden | O papel não tem permissão para o recurso ou a ação, ou o tenant está suspenso ou teve o acesso negado. | Solicite a permissão ou verifique o tenant. |
| `TED-0080` | 503 | Tenant Configuration Missing | Falta uma configuração obrigatória da instituição, como os limites de uso. Em um envio, também um pacote de tarifas que tira uma tarifa do valor enviado, ou que o TED Lerian não consegue ler. | O administrador configura a política, ou faz o pacote de tarifas cobrar toda tarifa do remetente. |
| `TED-0081` | 422 | Cutoff After Official Close | O cut-off é posterior ao fechamento oficial. | Envie um horário igual ou anterior ao fechamento oficial. |
| `TED-1000` | 503 | Ledger Unavailable | O ledger não confirmou o resultado. A operação já pode estar no ledger. | Leia o status do recurso antes de agir de novo. |
| `TED-1001` | 422 | Ledger Rejected | O ledger recusou por uma regra de negócio (conta inativa, ativo, rota). Em uma devolução de TED recebida, a conta do cliente não cobre o estorno: o crédito é mantido e a TED vai para revisão manual. | Verifique a conta e a configuração. |
| `TED-1010` | 503 | Rail Unavailable | Em um cancelamento, a resposta do conector do STR é desconhecida, e a solicitação de cancelamento continua registrada. Em um envio, o conector do STR não alcançou o STR e não armazenou nada. Em uma devolução de TED recebida, a resposta do STR é desconhecida. Qualquer crédito já foi estornado. A devolução continua solicitada até a conciliação ou a revisão manual. | Em um cancelamento, tente de novo com o mesmo `X-Idempotency` e o mesmo `reason`. Em um envio, envie uma nova TED se ainda for o caso. Em uma devolução, leia o status da TED antes de agir de novo. |
| `TED-1011` | 422 em uma devolução; — em um envio | Rail Rejected | O conector recusou o comando por uma validação de protocolo. Em uma devolução de TED recebida, o STR recusou a devolução, ou a solicitação de devolução está malformada ou não pode ser enviada. Nenhum valor saiu da instituição, e a TED vai para revisão manual. | Corrija os dados. Em uma devolução, leia o status da TED. Ela está em `MANUAL_REVIEW`, ou continua em `RETURN_REQUESTED` até o TED Lerian levá-la à revisão. |
| `TED-1012` | 503 | Rail Capability Unavailable | O conector não oferece a capacidade, como cancelar um lançamento pendente no STR. Uma nova tentativa recebe a mesma resposta. | Acompanhe a transferência até ela chegar a um status final. |
| `TED-1013` | — | Rail Closed Without STR Decision | O trilho encerrou a TED sem decisão do STR (alçada negada ou expirada). | Não altere os dados. Verifique a alçada ou o caso no trilho e envie uma nova TED se ainda for o caso. |
| `TED-1020` | 503 | Account Registry Unavailable | O cadastro de contas está indisponível. | Tente de novo. |
| `TED-1021` | 422 | Account Not Found | A conta ou o seu titular não foi encontrado no cadastro. | Verifique os dados. |
| `TED-9000` | 500 | Internal Error | Uma falha inesperada. | Contate o suporte com o `X-Request-Id`. |
| `TED-9002` | 503 | Service Unavailable | O serviço está indisponível. Com o detail "The audit trail is unavailable, so nothing was changed", a trilha de auditoria não consegue registrar uma mudança de política ou uma decisão de operador (desbloqueio, revisão de conciliação, revisão de TED recebida, devolução de TED recebida), e nada foi alterado. | Tente de novo mais tarde com o mesmo `X-Idempotency`. |
| `TED-9003` | 413 | Request Entity Too Large | O body da requisição é maior do que o servidor HTTP aceita. | Envie um body menor. |
| `TED-9004` | 4xx | O texto do status HTTP | O servidor HTTP recusa a requisição e nenhum outro código se aplica, por exemplo `405` quando o caminho não aceita o método, ou `415`. O `detail` indica a causa. | Corrija a requisição. |


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