Bank Transfer error list

Error format

{
  "type": "https://errors.lerian.studio/v1/BTF-0203",
  "title": "Conflict",
  "status": 409,
  "detail": "this initiation has already been processed",
  "code": "BTF-0203",
  "category": "deterministic",
  "requestId": "6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f",
  "service": "plugin",
  "transferId": "019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d"
}

Field definitions

type – A URI that names the error code: https://errors.lerian.studio/v1/<code>.
title – The HTTP status text.
status – The HTTP status code.
detail – A human-readable explanation of this error.
code – A stable identifier for the error (e.g. BTF-0010).
requestId – Correlation ID for the request. Present even when empty. Include it in support requests.
service – The service or domain that produced the error (e.g. plugin, crm, midaz, fees, jd_spb).
category – Machine-readable error category for retry decisions: deterministic, transient, rate_limit, or plugin.
errors – Optional. One entry for each rejected field, with message and location (body.<field> or query.<field>).
upstream – Optional. The error code that an upstream provider, such as JD SPB, returned. It is on upstream.code, verbatim.

Bank Transfer errors

The following errors can occur when interacting with the Bank Transfer endpoints. Each error follows our standard structure. Refer to the tables below for a list of possible error codes, what they mean, and how to resolve them.

202

`code`	Name	Description
BTF-9010	Transfer Escalated To Reconciliation	The TED OUT advance failed, and the plugin escalated the transfer to reconciliation. The Midaz hold is intact. Poll `GET /v1/transfers/{transferId}` for the final status. The body is a problem document, not a transfer response.

400

`code`	Name	Description
BTF-0001	Invalid Input	The request contains invalid fields. Check the field details below.
BTF-0210	Retention Reason Invalid	The retention reason filter is outside the declared vocabulary.
BTF-0214	Retained State Invalid	The `state` filter is not `open`, `closed`, or `all`.

401

`code`	Name	Description
BTF-0401	Unauthorized	Authentication failed. The token is missing, invalid, or expired.

403

`code`	Name	Description
BTF-0403	License Invalid	Organization is not licensed. Contact support to activate your license.
BTF-0405	Forbidden	Insufficient permissions to perform this action.
BTF-0406	Operator Identity Required	The token does not identify a person (a service account or a token of another type), so the plugin cannot attribute this by-hand write to an operator. No grant fixes this. Call the endpoint with a user token.
BTF-0408	Tenant Suspended	The tenant manager refused this tenant access to the service.

404

`code`	Name	Description
BTF-0200	Transfer Not Found	Transfer not found
BTF-0201	Initiation Not Found	Initiation not found or belongs to different organization
BTF-0215	Unsettled Incoming Not Found	The message carries nothing that an operator can close. A message that does not exist returns the same code.
BTF-0306	Webhook Not Found	The webhook registration does not exist or belongs to another tenant.
BTF-0404	Organization Not In Tenant	`X-Organization-Id` names an organization that this tenant does not operate.
BTF-0407	Tenant Not Found	The tenant manager does not know the tenant that the token names.
BTF-0500	Account Not Found	Sender account does not exist in CRM
BTF-1092	Signing Artifact Not Found	The signing artifact was not found.
BTF-2001	Midaz Account Not Found	The Midaz account was not found.

409

`code`	Name	Description
BTF-0012	Duplicate Transfer	Duplicate transfer detected
BTF-0016	Idempotency Request In Progress	A request under this `X-Idempotency` key still holds the in-flight lease. While the first request still runs, resend the identical request after the `Retry-After` interval. If an earlier request under this key answered 5xx, no answer comes from it: read the resource, and send the work under a new key only if it did not land.
BTF-0018	Idempotency Replay Unavailable	The request under this `X-Idempotency` key already completed, and its response was too large to store for replay. Read the resource. Do not resend under a new key, because that runs the work a second time.
BTF-0107	TED IN Poller Busy	Another TED IN poll or replay cycle is already in progress for this tenant. Try again when it finishes.
BTF-0108	Resume Gap Not Durable	The poller resume was refused. The receive-state-unknown latch has no durable reconciliation gap yet, so the poller stays stopped. Retry after the gap row is persisted.
BTF-0109	Manual Retry State Mismatch	The transfer is not a `TED_OUT` parked in `PROCESSING` and `MANUAL_REVIEW` (or its legacy equivalent `EXHAUSTED`) with a preserved hold. Nothing was written, and a repeat cannot change that.
BTF-0110	Manual Resolution Not Allowed	This action does not resolve this transfer, and nothing was resolved. Read the transfer again.
BTF-0111	Ledger State Contradicts Resolution	The ledger contradicts the requested resolution. Issue the other action.
BTF-0112	Initiation Predates Scoped Routing	The initiation was created before ledger-scoped routing and cannot be processed. Nothing was written. Initiate the transfer again.
BTF-0113	Transfer Scope Not Repairable	The transfer has nothing to repair, for example because its ledger is already set or another operator repaired it first. Read the transfer again.
BTF-0114	Transfer Scope Ledger Mismatch	CRM reports a different ledger for the account of this transfer. Nothing was written, and the response does not echo either ledger.
BTF-0115	Posting Not Completable	The ledger holds a live posting for this chargeback, and this service cannot complete the chargeback on it. Read that transaction in the ledger, settle what remains outside this platform, and close the transfer with `SETTLED_BY_HAND`.
BTF-0116	Refund Cancelled	A hand `RE_POST` filed its refund, and the ledger cancelled it, so it paid nothing. Issue `RE_POST` again to file a new refund.
BTF-0117	Refunded Twice	The ledger holds more than one live refund for this chargeback. Nothing was posted, and the transfer was not closed. Do not issue `RE_POST` again. Read every transaction in `transactionIds`. If `liveRefundSetComplete` is `false`, `transactionIds` does not name every live refund: find the others in the ledger. Return the surplus to the beneficiary outside this platform, then close the transfer with `SETTLED_BY_HAND`.
BTF-0203	Already Processed	This initiation has already been processed
BTF-0216	Unsettled Incoming Already Closed	Somebody already recorded where this money went. Read that decision before you write another.
BTF-0217	Retention Resolves Automatically	This retention ends by itself, so do not close it by hand. The credit lands once its ledger route or ownership answer arrives. Fix that configuration instead.
BTF-0305	DLQ Retries Exceeded	The DLQ message exceeded the maximum number of manual retry attempts.
BTF-0307	Rotation Conflict	A signing-secret rotation is already in progress for this webhook registration. Retry the rotation.
BTF-1094	Signing Artifact Used	The signing artifact was already used.
BTF-1095	Signing Artifact Mismatch	The signing artifact does not match the expected payload.
BTF-2002	Midaz State Conflict	Midaz reported a transaction state conflict.
BTF-9009	Reconciliation Cycle Busy	A reconciliation sweep is already in progress. Retry after the `Retry-After` delay.

410

`code`	Name	Description
BTF-0202	Initiation Expired	Initiation expired after 24 hours. Create a new initiation.
BTF-1093	Signing Artifact Expired	The signing artifact expired. The error carries `expiresAt`.

422

`code`	Name	Description
BTF-0002	Domain Validation	The payload violates a domain rule, for example an invalid webhook endpoint URL or an unsupported event type.
BTF-0003	Payload Field Missing	The STR0008 payload is missing a required field.
BTF-0004	Unsupported Type	The operation does not support this transfer type, for example signing prepare on a transfer that is not a TED OUT.
BTF-0010	Operating Hours Violation	Transfers can only be initiated Monday-Friday between 06:30 and 17:00 Brasília time
BTF-0011	Limit Exceeded	Transfer amount exceeds daily limit
BTF-0013	Constraint Violation	The data violates a database constraint.
BTF-0014	Idempotency Outcome Unrecorded	An earlier request under this `X-Idempotency` key answered 5xx, so the key is fenced for the retention window. Read the resource and, only if the work did not land, send the identical request under a new key.
BTF-0015	Idempotency Record Unusable	This service cannot read the idempotency record under this key. Read the resource and, only if the work did not land, send the identical request under a new key.
BTF-0017	Idempotency Key Reused	This `X-Idempotency` key was already used for a different request. A repeat must be byte-identical, and a new request needs a new key.
BTF-0204	Cannot Cancel	Transfer cannot be cancelled in its current status. Only CREATED or PENDING transfers can be cancelled.
BTF-0501	CRM Invalid Response	The CRM account record is missing a required field (`organizationId`). Contact your platform team to fix the account data in the CRM.
BTF-1001	JD SPB Rejected	JD SPB rejected the transfer. The JD code is on `upstream.code`.
BTF-1090	Signing Artifact Required	A TED OUT needs a signing artifact before it is processed.
BTF-1096	Invalid Signature	The digital signature is missing or invalid.
BTF-2003	Midaz Validation	Midaz rejected the transaction request.
BTF-2004	Midaz Transaction Denied	The Tracer of the Midaz ledger denied the transfer under a limit or a rule. Nothing was posted.
BTF-2005	Midaz Fee Refused	In `native` fee mode, the Midaz Fees Engine refused to price the transfer. For example, two fee packages match it equally (Midaz refuses such a posting with error `0198`), or a fee taken out of the amount is larger than the amount. This code covers every Midaz fee error, `0179` to `0233`. Nothing was posted. Correct the fee packages, then initiate the transfer again.
BTF-3002	Deductible TED OUT Fee	The fee package that matches a TED OUT takes the fee out of the amount. A TED OUT charges its fee on top of the amount, so set `isDeductibleFrom: false` on the fees of that package and initiate again. Nothing reached JD. When the error carries `transferId`, an earlier process call of this initiation reserved that transfer, and any ledger hold it placed stays until an operator releases it.
BTF-4003	Payee Not Held Here	The recipient account is on this institution, but this engine does not hold it. The transfer was not created.
BTF-4004	Payee Key Unusable	The CRM record of the recipient cannot be keyed for the ownership map. Correct the branch and account of the recipient in CRM. A retry does not help. The transfer was not created.

When JD SPB answers an error with its own code, the problem document carries that code verbatim on upstream.code. Examples are ACE95 for request timeouts, AAC90 for invalid signature rejections, and ALN01 for control-number-not-found responses. Refer to the JD SPB vendor documentation for the full list and the corresponding retry policy for each code.

429

`code`	Name	Description
BTF-0429	Rate Limited	Too many requests. Retry after the interval indicated by the `Retry-After` header.

Rate-limit responses use the rate_limit category and include a Retry-After header. Back off using HTTP status 429 and that header.

500

`code`	Name	Description
BTF-0106	Manual Reconciliation Required	A cancellation could not confirm or record the Midaz hold state. Manual reconciliation is required.
BTF-9000	Internal Error	An unexpected error occurred. Contact support if it persists.
BTF-9002	Post-Dispatch Failure	The transfer was sent, but the bookkeeping after dispatch failed. Do not retry. The error carries `transferId` and `transferStatus`.
BTF-9006	Unexpected Empty Response	The service layer returned an unexpected empty response.
BTF-9011	Transfer Stranded	When the TED OUT advance and its escalation to reconciliation both failed, reconciliation picks up the transfer within ten minutes and releases its hold once the clearing house is open again, so do not retry `/process`. When a duplicate TED OUT request was caught after the Midaz hold and its revert failed, check Midaz for an unreconciled hold before you retry `/process`.
BTF-9012	Origin ISPB Missing	The deployment has no origin ISPB configured, so the transfer type cannot be classified.
BTF-9014	Ledger Moved, Row Unwritten	The ledger moved, and the transfer did not reach its final state. Read the transfer, then send the identical request again under a new `X-Idempotency` key. The repeat converges on the ledger state of this transfer, so it cannot move money twice. If the repeat does not clear the error, the transfer needs manual inspection.

502

`code`	Name	Description
BTF-0501	CRM Invalid Response	The CRM returned an ambiguous or unparseable response. Contact your platform team. (BTF-0501 also appears under 422 when the CRM record is missing a required field.)
BTF-1007	JD Credentials Rejected	JD SPB rejected the credentials. The JD code is on `upstream.code`.
BTF-1008	JD Certificate Rejected	JD SPB rejected the signing certificate or the digital signature. The JD code is on `upstream.code`.
BTF-1009	JD Configuration Rejected	JD SPB rejected the configuration. The JD code is on `upstream.code`.
BTF-3001	Fees Invalid Response	The fee service returned an invalid or unparseable response. Contact your platform team.
BTF-4001	Ownership Map Invalid Response	The ownership map returned an answer that could not be used. The transfer was not settled.

503

`code`	Name	Description
BTF-0019	Idempotency Key Unprotected	The work under this `X-Idempotency` key ran, and neither its response nor its outcome fence could be stored. The key protects nothing, so a resend can run the operation a second time. Read the resource before you send anything else.
BTF-0020	Idempotency Receipt Unstored	The work under this `X-Idempotency` key ran, and its response could not be stored for replay, but the key is still held. Read the resource, and resend under a new key only if the work did not land.
BTF-0402	Authorization Unavailable	The Access Manager did not answer, so the request was refused. Try again later.
BTF-0409	Tenant Resolution Unavailable	The tenant manager or its connection pool did not answer, so the database of this tenant could not be resolved. Try again later.
BTF-0410	Tenant Not Provisioned	The tenant has no database for this service. A retry does not help: the onboarding of the tenant has to be completed.
BTF-0502	CRM Service Unavailable	Unable to validate account. The CRM service is temporarily unavailable. Try again later.
BTF-0503	CRM Auth Failure	CRM rejected the credentials of Bank Transfer.
BTF-1000	JD SPB Unavailable	JD SPB is unavailable.
BTF-1003	JD SPB Timeout	JD SPB timed out.
BTF-2000	Midaz Unavailable	Unable to process transfer. The Midaz ledger service is temporarily unavailable, or it refused the Midaz credentials of Bank Transfer. If Midaz is unavailable, try again later. A refused credential does not clear on retry: check its permissions. In `native` fee mode, it needs `packages` (`get`) and `estimates` (`post`). With `MIDAZ_FEE_MODE=native` set explicitly, it also needs `organizations` (`get`).
BTF-3000	Fee Service Unavailable	Unable to calculate fee. The fee service is temporarily unavailable. Try again later.
BTF-4000	Ownership Map Unavailable	The ownership map is unavailable, and the transfer was not settled. Try again later.
BTF-4002	Ownership Lookup Refused Locally	The plugin refused the ownership lookup locally. Nothing was sent, and the transfer was not settled.
BTF-9000	Idempotency Store Unavailable	The idempotency store was not available, so the plugin did not run the request. Send the same request again under the same `X-Idempotency` key.
BTF-9001	Usage Limit Service Unavailable	The usage-limit service is temporarily unavailable, so the transfer cannot proceed.
BTF-9003	Duplicate Guard Unavailable	The duplicate check service is unavailable.
BTF-9004	Reconciliation Subsystem Unavailable	The reconciliation subsystem is unavailable.
BTF-9005	Dependency Not Configured	A required service dependency is not configured.
BTF-9007	Repository Timeout	A database operation timed out.
BTF-9008	Repository Unavailable	The database is unavailable.
BTF-9015	Route Config Missing	A routing configuration could not be read. The `systemplaneKey` field names the configuration document.
BTF-9016	Schema Not Ready	The database of this tenant cannot record this write, and nothing was written. Apply the pending migrations to this tenant, then send the identical request again under a new `X-Idempotency` key.
BTF-9017	Organization Scope Unavailable	The organization list of the tenant is absent or unreadable. Retry with the same idempotency key once it is configured.
BTF-9018	Tenant ISPB Set Invalid	The tenant binds more than one ISPB, so its identity on the clearing house cannot be decided. Nothing was written.

Transfers API

Dashboard & Reconciliation API

TED In Operations API

Webhooks API

Webhook DLQ API

Error handling

Bank Transfer error list

Bank Transfer errors

202

400

401

403

404

409

410

422

429

500

502

503

​Bank Transfer errors

​202

​400

​401

​403

​404

​409

​410

​422

​429

​500

​502

​503

Bank Transfer errors

202

400

401

403

404

409

410

422

429

500

502

503