Developers / Contract reference

Errors

AXIS contract error codes, what raises them and how to fix them, plus the token and host errors that can fail a call.

How errors surface#

A failed AXIS call keeps nothing of what it did: no transfer, no order change, no approval and no event.

• Simulation. Most failures show up when the transaction is simulated, before anything is signed. The RPC simulateTransaction response carries an error string such as HostError: Error(Contract, #709), followed by a diagnostic event log. Nothing is submitted and nothing is paid.
• On-chain. A transaction that passed simulation can still fail when the ledger changed before it was applied, for example a maker spent their balance. The transaction fails as a whole with an invoke_host_function result such as trapped or resource_limit_exceeded, and its fee is charged.
• JS client. AxisContractClient (and every high-level class built on it) turns an AXIS code found in a simulation error into Error('Contract execution error: #709 NotFilled') with a numeric code property. An error raised by another contract, normally a token transfer during settlement, becomes an Error with tokenError: true, its numeric code and, when the diagnostic log names it, the contract that raised it, and its message says that either side of the transfer may be at fault. Any other simulation error, including host errors, is rethrown unchanged as the RPC's error string. A transaction that fails on-chain throws Error('Transaction <hash> failed: <result>') with a hash property. See Contract client.

ContractErrors maps every code to its name:

import {ContractErrors} from '@axis-markets/client'

console.log(ContractErrors[722].message) // 'AssetPriceOracleFetchFailed'

// account, XLM and USDC as in the Getting started example
try {
    await account.sell({selling: XLM, buying: USDC, amount: 1_000_000_000n, price: 250_000_000_000_000_000n})
} catch (e) {
    const known = ContractErrors[e?.code]
    if (e?.tokenError) {
        console.log(`Token ${e.contract} failed a transfer with #${e.code}: check the balance and allowance, then the makers' trustlines`)
    } else if (e?.code === 722) {
        console.log('No fresh oracle price for this market: requote it, then retry')
    } else if (known) {
        console.log(`AXIS error ${e.code} ${known.message}`)
    } else {
        throw e
    }
}

Contract errors#

Codes come from errors.rs. Each function on the Functions page lists the codes it raises.

Notes on frequent cases:

• A Limit trade needs a market and, while the minimum order value is enabled, a fresh cached price, even when it fills completely. Use Fill when you do not want an order on the book. 721 and 722 never affect fills, swaps, crossfills and removals.
• 708 points at the receiving account's trustline, 712 at the issuer's authorization of the contract itself. Failure modes sorts every failure by who is at fault.
• Missing or wrong signatures are not contract errors. See host errors.

Token errors#

AXIS moves tokens with transfer_from and transfer on the token contracts. When a token call fails, the token's own error ends the call. For a Stellar Asset Contract it looks like an AXIS code but with a small number, for example HostError: Error(Contract, #10). The JS client reports it as an Error with tokenError: true, the token's code and the token contract (see How errors surface).

Where AXIS checks first and where it does not:

• A failed payment to a maker fails the whole call with the token's error, nothing moves and no maker is flagged. The error cannot tell a payer who cannot pay from a maker who cannot be credited although authorized (a full trustline), so check your own balance and allowance first, then leave out the maker whose line has no room and retry. In crossfill the payer is the taker order's owner, so this failure is never the caller's.
• A maker whose asset cannot be collected is skipped with a skip event in trade and crossfill. In a swap the failed maker transfer fails the whole call with the token's error.
• trade, update and crossfill check that the receiving account can hold the asset and fail with 708 before any transfer. swap has no such check, so a trader without a trustline for the output gets #13 or #11, and one with a full trustline #10. crossfill pays the taker order's owner and the caller with plain transfers, so a full trustline on either side fails the call with the token's error.

Custom SEP-41 tokens report their own error codes, and a token that lacks a function AXIS calls fails the call. See Custom tokens and Failure modes.

Host errors#

These come from the Soroban host, not from AXIS or a token:

Two more failures are not contract errors at all:

• Archived entries. An order, market or token entry that was not touched for a long time is archived. Simulation marks the archived entries a call touches for restore, and the transaction restores them and pays their rent. An archived entry declared without that mark, such as a listed spare order the simulation did not reach, fails the transaction when it is applied. See Archival and restore.
• Footprint and resource limits. A transaction declares the ledger entries and resources it may use. If the book changes between simulation and execution and the call needs an entry it did not declare, the transaction fails. The JS client declares the entries of every listed order and maker to avoid this (see footprint completion).