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

{
  "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.