> ## 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": "about:blank",
  "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. Defaults to `about:blank`.
* **`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`, `TED-1011` and `TED-1013` are never error responses: they arrive in `rejection.code` of a transfer in status `REJECTED`. On a send, `TED-1001` arrives 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 or out of format (see `errors`). | Fix the fields listed. |
| `TED-0003` | 422 | Invalid Purpose Code | `purposeCode` is outside the official domain. | Use a 5-digit code from the SFN domain 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 document is not a CPF (11 digits) or a CNPJ (14 digits), digits only. | 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 body. On `POST /v1/transfers`, also a key that already created a transfer, after the `X-TTL` window too. | 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 sent shortly after another one. | Wait, or read the existing transfer. |
| `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, the calendar or the configuration is unavailable. TED Lerian refuses rather than guessing. | 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 | The fee calculation is unavailable and the institution's policy does not allow sending without a fee. | Retry. |
| `TED-0060` | 409 | Invalid State Transition | The action does not fit the current status. | 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. | The administrator configures the policy. |
| `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). | Check the account and the configuration. |
| `TED-1010` | 503 | Rail Unavailable | The answer of the STR connector to a cancellation is unknown. The cancellation request stays recorded. | Retry with the same `X-Idempotency` and the same `reason`. |
| `TED-1011` | — | Rail Rejected | The connector refused the command for a protocol validation. | Fix the data. |
| `TED-1012` | 503 | Rail Capability Unavailable | The connector does not offer the capability, such as cancelling a pending entry at the STR. | 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` | 400 | Bad Request | The HTTP server refuses the request and no other code applies, for example when the path does not accept the method. `detail` names the cause. | Fix the request. |


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