Skip to main content

create_transfers

Create one or more Transfers. A successfully created transfer will modify the amount fields of its debit and credit accounts.

Event​

The transfer to create. See Transfer for constraints.

Result​

Results are listed in this section in order of descending precedence — that is, if more than one error is applicable to the transfer being created, only the result listed first is returned.

ok​

The transfer was successfully created; did not previously exist.

Note that ok is generated by the client implementation; the network protocol does not include a result when the transfer was successfully created.

linked_event_failed​

The transfer was not created. One or more of the other transfers in the linked chain is invalid, so the whole chain failed.

linked_event_chain_open​

The transfer was not created. The Transfer.flags.linked flag was set on the last event in the batch, which is not legal. (flags.linked indicates that the chain continues to the next operation).

imported_event_expected​

The transfer was not created. The Transfer.flags.imported was set on the first transfer of the batch, but not all transfers in the batch. Batches cannot mix imported transfers with non-imported transfers.

imported_event_not_expected​

The transfer was not created. The Transfer.flags.imported was expected to not be set, as it's not allowed to mix transfers with different imported flag in the same batch. The first transfer determines the entire operation.

timestamp_must_be_zero​

This result only applies when Account.flags.imported is not set.

The transfer was not created. The Transfer.timestamp is nonzero, but must be zero. The cluster is responsible for setting this field.

The Transfer.timestamp can only be assigned when creating transfers with Transfer.flags.imported set.

imported_event_timestamp_out_of_range​

This result only applies when Transfer.flags.imported is set.

The transfer was not created. The Transfer.timestamp is out of range, but must be a user-defined timestamp greater than 0 and less than 2^63.

imported_event_timestamp_must_not_advance​

This result only applies when Transfer.flags.imported is set.

The transfer was not created. The user-defined Transfer.timestamp is greater than the current cluster time, but it must be a past timestamp.

reserved_flag​

The transfer was not created. Transfer.flags.reserved is nonzero, but must be zero.

id_must_not_be_zero​

The transfer was not created. Transfer.id is zero, which is a reserved value.

id_must_not_be_int_max​

The transfer was not created. Transfer.id is 2^128 - 1, which is a reserved value.

exists_with_different_flags​

A transfer with the same id already exists, but with different flags.

exists_with_different_pending_id​

A transfer with the same id already exists, but with a different pending_id.

exists_with_different_timeout​

A transfer with the same id already exists, but with a different timeout.

exists_with_different_debit_account_id​

A transfer with the same id already exists, but with a different debit_account_id.

exists_with_different_credit_account_id​

A transfer with the same id already exists, but with a different credit_account_id.

exists_with_different_amount​

A transfer with the same id already exists, but with a different amount.

If the transfer has flags.balancing_debit or flags.balancing_credit set, then the actual amount transferred exceeds this failed transfer's amount.

exists_with_different_user_data_128​

A transfer with the same id already exists, but with a different user_data_128.

exists_with_different_user_data_64​

A transfer with the same id already exists, but with a different user_data_64.

exists_with_different_user_data_32​

A transfer with the same id already exists, but with a different user_data_32.

exists_with_different_ledger​

A transfer with the same id already exists, but with a different ledger.

exists_with_different_code​

A transfer with the same id already exists, but with a different code.

exists​

A transfer with the same id already exists.

If the transfer has flags.balancing_debit or flags.balancing_credit set, then the existing transfer may have a different amount, limited to the maximum amount of the transfer in the request.

If the transfer has flags.post_pending_transfer set, then the existing transfer may have a different amount:

  • If the original posted amount was less than the pending amount, then the transfer amount must be equal to the posted amount.
  • Otherwise, the transfer amount must be greater than or equal to the pending amount.
Client release < 0.16.0

If the transfer has flags.balancing_debit or flags.balancing_credit set, then the existing transfer may have a different amount, limited to the maximum amount of the transfer in the request.

Otherwise, with the possible exception of the timestamp field, the existing transfer is identical to the transfer in the request.

To correctly recover from application crashes, many applications should handle exists exactly as ok.

id_already_failed​

The transfer was not created. A previous transfer with the same id failed due to one of the following transient errors:

Transient errors depend on the database state at a given point in time, and each attempt is uniquely associated with the corresponding Transfer.id. This behavior guarantees that retrying a transfer will not produce a different outcome (either success or failure).

Without this mechanism, a transfer that previously failed could succeed if retried when the underlying state changes (e.g., the target account has sufficient credits).

Note: The application should retry an event only if it was unable to acknowledge the last response (e.g., due to an application restart) or because it is correcting a previously rejected malformed request (e.g., due to an application bug). If the application intends to submit the transfer again even after a transient error, it must generate a new idempotency id.

Client release < 0.16.4

The id is never checked against failed transfers, regardless of the error. Therefore, a transfer that failed due to a transient error could succeed if retried later.

flags_are_mutually_exclusive​

The transfer was not created. A transfer cannot be created with the specified combination of Transfer.flags.

Flag compatibility (✓ = compatible, ✗ = mutually exclusive):

debit_account_id_must_not_be_zero​

The transfer was not created. Transfer.debit_account_id is zero, but must be a valid account id.

debit_account_id_must_not_be_int_max​

The transfer was not created. Transfer.debit_account_id is 2^128 - 1, but must be a valid account id.

credit_account_id_must_not_be_zero​

The transfer was not created. Transfer.credit_account_id is zero, but must be a valid account id.

credit_account_id_must_not_be_int_max​

The transfer was not created. Transfer.credit_account_id is 2^128 - 1, but must be a valid account id.

accounts_must_be_different​

The transfer was not created. Transfer.debit_account_id and Transfer.credit_account_id must not be equal.

That is, an account cannot transfer money to itself.

pending_id_must_be_zero​

The transfer was not created. Only post/void transfers can reference a pending transfer.

Either:

pending_id_must_not_be_zero​

The transfer was not created. Transfer.flags.post_pending_transfer or Transfer.flags.void_pending_transfer is set, but Transfer.pending_id is zero. A posting or voiding transfer must reference a pending transfer.

pending_id_must_not_be_int_max​

The transfer was not created. Transfer.pending_id is 2^128 - 1, which is a reserved value.

pending_id_must_be_different​

The transfer was not created. Transfer.pending_id is set to the same id as Transfer.id. Instead it should refer to a different (existing) transfer.

timeout_reserved_for_pending_transfer​

The transfer was not created. Transfer.timeout is nonzero, but only pending transfers have nonzero timeouts.

closing_transfer_must_be_pending​

The transfer was not created. Transfer.flags.pending is not set, but closing transfers must be two-phase pending transfers.

If either Transfer.flags.closing_debit or Transfer.flags.closing_credit is set, Transfer.flags.pending must also be set.

This ensures that closing transfers are reversible by voiding the pending transfer, and requires that the reversal operation references the corresponding closing transfer, guarding against unexpected interleaving of close/unclose operations.

amount_must_not_be_zero​

Deprecated: This error code is only returned to clients prior to release 0.16.0. Since 0.16.0, zero-amount transfers are permitted.

Client release < 0.16.0

The transfer was not created. Transfer.amount is zero, but must be nonzero.

Every transfer must move value. Only posting and voiding transfer amounts may be zero — when zero, they will move the full pending amount.

ledger_must_not_be_zero​

The transfer was not created. Transfer.ledger is zero, but must be nonzero.

code_must_not_be_zero​

The transfer was not created. Transfer.code is zero, but must be nonzero.

debit_account_not_found​

The transfer was not created. Transfer.debit_account_id must refer to an existing Account.

This is a transient error. The Transfer.id associated with this particular attempt will always fail upon retry, even if the underlying issue is resolved. To succeed, a new idempotency id must be submitted.

credit_account_not_found​

The transfer was not created. Transfer.credit_account_id must refer to an existing Account.

This is a transient error. The Transfer.id associated with this particular attempt will always fail upon retry, even if the underlying issue is resolved. To succeed, a new idempotency id must be submitted.

accounts_must_have_the_same_ledger​

The transfer was not created. The accounts referred to by Transfer.debit_account_id and Transfer.credit_account_id must have an identical ledger.

Currency exchange is implemented with multiple transfers.

transfer_must_have_the_same_ledger_as_accounts​

The transfer was not created. The accounts referred to by Transfer.debit_account_id and Transfer.credit_account_id are equivalent, but differ from the Transfer.ledger.

pending_transfer_not_found​

The transfer was not created. The transfer referenced by Transfer.pending_id does not exist.

This is a transient error. The Transfer.id associated with this particular attempt will always fail upon retry, even if the underlying issue is resolved. To succeed, a new idempotency id must be submitted.

pending_transfer_not_pending​

The transfer was not created. The transfer referenced by Transfer.pending_id exists, but does not have flags.pending set.

pending_transfer_has_different_debit_account_id​

The transfer was not created. The transfer referenced by Transfer.pending_id exists, but with a different debit_account_id.

The post/void transfer's debit_account_id must either be 0 or identical to the pending transfer's debit_account_id.

pending_transfer_has_different_credit_account_id​

The transfer was not created. The transfer referenced by Transfer.pending_id exists, but with a different credit_account_id.

The post/void transfer's credit_account_id must either be 0 or identical to the pending transfer's credit_account_id.

pending_transfer_has_different_ledger​

The transfer was not created. The transfer referenced by Transfer.pending_id exists, but with a different ledger.

The post/void transfer's ledger must either be 0 or identical to the pending transfer's ledger.

pending_transfer_has_different_code​

The transfer was not created. The transfer referenced by Transfer.pending_id exists, but with a different code.

The post/void transfer's code must either be 0 or identical to the pending transfer's code.

exceeds_pending_transfer_amount​

The transfer was not created. The transfer's amount exceeds the amount of its pending transfer.

pending_transfer_has_different_amount​

The transfer was not created. The transfer is attempting to void a pending transfer. The voiding transfer's amount must be either 0 or exactly the amount of the pending transfer.

To partially void a transfer, create a posting transfer with an amount less than the pending transfer's amount.

Client release < 0.16.0

To partially void a transfer, create a posting transfer with an amount between 0 and the pending transfer's amount.

pending_transfer_already_posted​

The transfer was not created. The referenced pending transfer was already posted by a post_pending_transfer.

pending_transfer_already_voided​

The transfer was not created. The referenced pending transfer was already voided by a void_pending_transfer.

pending_transfer_expired​

The transfer was not created. The referenced pending transfer was already voided because its timeout has passed.

imported_event_timestamp_must_not_regress​

This result only applies when Transfer.flags.imported is set.

The transfer was not created. The user-defined Transfer.timestamp regressed, but it must be greater than the last timestamp assigned to any Transfer in the cluster and cannot be equal to the timestamp of any existing Account.

imported_event_timestamp_must_postdate_debit_account​

This result only applies when Transfer.flags.imported is set.

The transfer was not created. Transfer.debit_account_id must refer to an Account whose timestamp is less than the Transfer.timestamp.

imported_event_timestamp_must_postdate_credit_account​

This result only applies when Transfer.flags.imported is set.

The transfer was not created. Transfer.credit_account_id must refer to an Account whose timestamp is less than the Transfer.timestamp.

imported_event_timeout_must_be_zero​

This result only applies when Transfer.flags.imported is set.

The transfer was not created. The Transfer.timeout is nonzero, but must be zero.

It's possible to import pending transfers with a user-defined timestamp, but since it's not driven by the cluster clock, it cannot define a timeout for automatic expiration. In those cases, the two-phase post or rollback must be done manually.

debit_account_already_closed​

The transfer was not created. Transfer.debit_account_id must refer to an Account whose Account.flags.closed is not already set.

This is a transient error. The Transfer.id associated with this particular attempt will always fail upon retry, even if the underlying issue is resolved. To succeed, a new idempotency id must be submitted.

credit_account_already_closed​

The transfer was not created. Transfer.credit_account_id must refer to an Account whose Account.flags.closed is not already set.

This is a transient error. The Transfer.id associated with this particular attempt will always fail upon retry, even if the underlying issue is resolved. To succeed, a new idempotency id must be submitted.

overflows_debits_pending​

The transfer was not created. debit_account.debits_pending + transfer.amount would overflow a 128-bit unsigned integer.

overflows_credits_pending​

The transfer was not created. credit_account.credits_pending + transfer.amount would overflow a 128-bit unsigned integer.

overflows_debits_posted​

The transfer was not created. debit_account.debits_posted + transfer.amount would overflow a 128-bit unsigned integer.

overflows_credits_posted​

The transfer was not created. debit_account.credits_posted + transfer.amount would overflow a 128-bit unsigned integer.

overflows_debits​

The transfer was not created. debit_account.debits_pending + debit_account.debits_posted + transfer.amount would overflow a 128-bit unsigned integer.

overflows_credits​

The transfer was not created. credit_account.credits_pending + credit_account.credits_posted + transfer.amount would overflow a 128-bit unsigned integer.

overflows_timeout​

The transfer was not created. transfer.timestamp + (transfer.timeout * 1_000_000_000) would exceed 2^63.

Transfer.timeout is converted to nanoseconds.

This computation uses the Transfer.timestamp value assigned by the replica, not the 0 value sent by the client.

exceeds_credits​

The transfer was not created.

The debit account has flags.debits_must_not_exceed_credits set, but debit_account.debits_pending + debit_account.debits_posted + transfer.amount would exceed debit_account.credits_posted.

This is a transient error. The Transfer.id associated with this particular attempt will always fail upon retry, even if the underlying issue is resolved. To succeed, a new idempotency id must be submitted.

Client release < 0.16.0

If flags.balancing_debit is set, then debit_account.debits_pending + debit_account.debits_posted + 1 would exceed debit_account.credits_posted.

exceeds_debits​

The transfer was not created.

The credit account has flags.credits_must_not_exceed_debits set, but credit_account.credits_pending + credit_account.credits_posted + transfer.amount would exceed credit_account.debits_posted.

This is a transient error. The Transfer.id associated with this particular attempt will always fail upon retry, even if the underlying issue is resolved. To succeed, a new idempotency id must be submitted.

Client release < 0.16.0

If flags.balancing_credit is set, then credit_account.credits_pending + credit_account.credits_posted + 1 would exceed credit_account.debits_posted.

Client libraries​

For language-specific docs see:

Internals​

If you're curious and want to learn more, you can find the source code for creating a transfer in src/state_machine.zig. Search for fn create_transfer( and fn execute(.