> ## 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.

# TED Lerian error list

> **TED Lerian** returns structured error responses with a stable code, so you can identify what went wrong and how to fix it.

**Error format**

Every error is an `application/problem+json` body (RFC 9457) with a stable `code`. Handle errors by `code`; the `detail` text can change.

```json JSON theme={null}
{
  "type": "https://errors.lerian.studio/v1/TED-0030",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Daily limit exceeded for the source account",
  "code": "TED-0030"
}
```

**Field definitions**

* **`code`** – A stable identifier for the error, in the format `TED-NNNN`.
* **`title`** – A short summary of the problem type.
* **`status`** – The HTTP status code.
* **`detail`** – A human-readable explanation of this occurrence.
* **`type`** – A reference to the problem type: `https://errors.lerian.studio/v1/` followed by the `code`.
* **`instance`** – Optional. A reference to this occurrence.
* **`errors`** – Optional. One entry for each rejected field, with `location`, `message` and `value`.
* **`upstream`** – Optional. The error that a proxied provider reported, with its own `code` and `message`, verbatim.

Every response, success or error, carries the `X-Request-Id` header. Include it in support requests.

## TED Lerian errors

***

The following errors can occur when you call the TED Lerian endpoints. `TED-0031` and `TED-1013` are never error responses: they arrive in `rejection.code` of a transfer in status `REJECTED`. On a send, `TED-1001`, `TED-1010` and `TED-1011` arrive the same way. If you retry a `POST /v1/transfers` whose first attempt got no answer, any refusal can still mean that the first attempt created the transfer: look it up with `GET /v1/transfers` before you send it with a new key.

| Code | HTTP | Title | When it happens | How to fix it |
| - | - | - | - | - |
| `TED-0001` | 400 | Bad Request | The JSON is malformed or a type is invalid. | Fix the request body. |
| `TED-0002` | 422 | Validation Failed | A required field is missing, out of format or outside the declared schema (see `errors`). On `PUT /v1/policy/ispb-bindings`, also a binding whose TED setup is incomplete. | Fix the fields listed, or create what the message names. |
| `TED-0003` | 422 | Invalid Purpose Code | `purposeCode` is unknown, or not in force on the date of the request, in the BACEN FinlddCli Domain Dictionary. | Use an active 5-digit code of that dictionary. |
| `TED-0004` | 422 | Description Required | `purposeCode=99999` without `description`. | Send `description`. |
| `TED-0005` | 422 | Recipient Bank Required | Neither `bankId` nor `bankCode` was sent, or both were. | Send exactly one. |
| `TED-0006` | 422 | Unknown Participant | `bankCode` or `bankId` is not in the STR participant list. | Check it with `GET /v1/participants`. |
| `TED-0007` | 422 | Document Mismatch | The check digits of the recipient's CPF or CNPJ are not valid. | Fix the document. |
| `TED-0008` | 400 | Account Header Required | `X-Account-Id` is missing or is not a UUID. | Send `X-Account-Id` with the source account. |
| `TED-0009` | 403 | Account Not Owned | `X-Account-Id` does not belong to the organization of the authenticated identity. | Use an account of your own organization. |
| `TED-0010` | 404 | Not Found | The resource does not exist in the institution. | Check the identifier. |
| `TED-0011` | 400 | Idempotency Key Required | `X-Idempotency` is missing on a request with an effect. | Send the header. |
| `TED-0012` | 422 | Idempotency Key Reuse | The same key with a different request, `metadata` included. On `POST /v1/transfers`, also after `X-TTL`. | A resource can already exist for this key. Look it up before you use a new key (for a transfer, `GET /v1/transfers` filtered by `client_reference`, or by `account_id` and date). |
| `TED-0013` | 409 | Idempotent Request In Flight | A request with the same key is still in progress. | Retry after `Retry-After`. |
| `TED-0014` | 409 | Duplicate Request | A materially identical request with a new key, sent shortly after another one. | Read the existing transfer. To retry a request, send the same key. |
| `TED-0015` | 409 | Reconciliation Already Running | A reconciliation cycle is already running. | Wait for the running cycle to finish. |
| `TED-0020` | 422 | Outside Operating Window | Outside the official schedule or after the institution's cut-off. | Send again in the next window (`GET /v1/policy/window`). |
| `TED-0021` | 422 | Non-Business Day | Weekend or bank holiday. | Send again on the next business day. |
| `TED-0022` | 503 | Operating Window Undetermined | The schedule or the configuration is unavailable, or the holiday calendar of the year of the date is not loaded. TED Lerian refuses rather than guessing. | If the year has no holiday calendar, load it with `PUT /v1/policy/holidays`. Otherwise, retry. |
| `TED-0030` | 422 | Usage Limit Exceeded | The per-transfer, daily or monthly limit was exceeded. | Lower the amount or wait for the period to roll over. |
| `TED-0031` | — | Insufficient Balance | The source account has insufficient balance. | Adjust the amount. |
| `TED-0040` | 503 | Fee Calculation Unavailable | TED Lerian cannot get the fee estimate. | Retry. |
| `TED-0060` | 409 | Invalid State Transition | The action does not fit the current status, or it is already applied (a return or a review decision). | Read the status and choose the right action. |
| `TED-0061` | 409 | Not Cancellable | The transfer is settled, incoming, already final, or awaiting reconciliation or exhausted (the real status is unknown). | Use a return when it applies; for awaiting reconciliation or exhausted, use `POST /v1/transfers/{transferId}/unblock` with evidence. |
| `TED-0062` | 409 | Not Returnable | The status does not allow a return. | — |
| `TED-0063` | 422 | Partial Return Not Allowed | A partial amount was sent. | Returns are always in full. |
| `TED-0064` | 422 | Invalid Return Code | `returnCode` is outside the official domain. | Use a valid `CodDevTransf`. |
| `TED-0065` | 422 | Evidence Required | An unblock without valid evidence, or without `rejectionCode` when `outcome=REJECTED`. | Send the STR evidence (and the rejection code when it applies). |
| `TED-0066` | 422 | Return Code Required | A manual review resolution with `action=RETURN` and no `returnCode`. | Send `returnCode`. |
| `TED-0067` | 409 | Held Return Carried By Transfer | A transfer that can still settle carries the held return you tried to close. | Do not close it: TED Lerian refunds the sender when that transfer settles. Reverse any ledger credit you made for it. |
| `TED-0070` | 401 | Unauthorized | The token is missing, invalid or expired. | Authenticate. |
| `TED-0071` | 403 | Forbidden | The role has no permission for the resource or action, or the product license is not valid for the organization. | Request the permission, or contact Lerian about the license. |
| `TED-0080` | 503 | Tenant Configuration Missing | A required institution configuration is missing, such as the usage limits. On a send, also a fee package that takes a fee from the amount sent, or that TED Lerian cannot read. | The administrator configures the policy, or makes the fee package charge every fee to the sender. |
| `TED-0081` | 422 | Cutoff After Official Close | The cut-off is later than the official close. | Send a time at or before the official close. |
| `TED-1000` | 503 | Ledger Unavailable | The ledger did not confirm the result. The operation can already be in the ledger. | Read the status of the resource before you act again. |
| `TED-1001` | 422 | Ledger Rejected | The ledger refused by a business rule (inactive account, asset, route). On a return of an incoming TED, the customer's account cannot cover the reversal: the credit is kept and the TED goes to manual review. | Check the account and the configuration. |
| `TED-1010` | 503 | Rail Unavailable | On a cancellation, the answer of the STR connector is unknown, and the cancellation request stays recorded. On a send, the STR connector could not reach the STR and stored nothing. On a return of an incoming TED, the answer of the STR is unknown. Any credit is already reversed. The return stays requested until reconciliation or manual review. | On a cancellation, retry with the same `X-Idempotency` and the same `reason`. On a send, send a new TED if it still applies. On a return, read the status of the TED before you act again. |
| `TED-1011` | 422 on a return; — on a send | Rail Rejected | The connector refused the command for a protocol validation. On a return of an incoming TED, the STR refused the return, or the return request is malformed or cannot be sent. No money left the institution, and the TED goes to manual review. | Fix the data. On a return, read the status of the TED. It is in `MANUAL_REVIEW`, or it stays in `RETURN_REQUESTED` until TED Lerian moves it to the review. |
| `TED-1012` | 503 | Rail Capability Unavailable | The connector does not offer the capability, such as cancelling a pending entry at the STR. A retry gets the same answer. | Track the transfer until it reaches a final status. |
| `TED-1013` | — | Rail Closed Without STR Decision | The rail closed the TED without an STR decision (approval denied or expired). | Do not change the data. Check the approval or the case on the rail, and send a new TED if it still applies. |
| `TED-1020` | 503 | Account Registry Unavailable | The account registry is unavailable. | Retry. |
| `TED-1021` | 422 | Account Not Found | The account or its holder was not found in the registry. | Check the data. |
| `TED-9000` | 500 | Internal Error | An unexpected failure. | Contact support with the `X-Request-Id`. |
| `TED-9002` | 503 | Service Unavailable | The service is unavailable, for example when the audit trail cannot record a policy change. | Retry later. |
| `TED-9003` | 413 | Request Entity Too Large | The request body is larger than the HTTP server accepts. | Send a smaller body. |
| `TED-9004` | 4xx | The HTTP status text | The HTTP server refuses the request and no other code applies, for example `405` when the path does not accept the method, or `415`. `detail` names the cause. | Fix the request. |


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