Errors and rejections

A Cosmos transaction can fail in four places, and telling them apart is the whole job: each has a different cause, a different remedy, and a different effect on your account.

The first three cost nothing but the round trip and leave the sequence you signed at still valid. Only the last consumed gas and burned a sequence number.

The distinction that catches people is between rows three and four, because both surface on the transaction query. Row three means the transaction was admitted and the world changed underneath it — the recipient was blacklisted, the issuer paused — so it can be re-signed at the same sequence once the cause is addressed. Row four means your message ran and failed. Read codespace: a compliance codespace on a transaction query is row three.

The EVM path fails differently; "EVM-side failures" at the end of this page covers it.

Reading a rejection

Two fields carry the answer:

• codespace names the module that produced the error.
• raw_log carries the readable message, already assembled: the offending address, amount or mismatch, followed by the error's registered text.

recipient=hkchain1abc…: address is blacklisted
payload tier="full" does not match sender's KYC-registered tier="minimal" (level=LEVEL_RETAIL_BASIC)

code is a per-module number and is only meaningful with its codespace. Match on the pair if you must branch in code; prefer matching on nothing and surfacing raw_log.

Compliance gate rejections

Five gates can reject. Each maps to one registered error in the compliance codespace:

Diagnosing a Travel Rule rejection

Code 20 covers several distinct failures. The message distinguishes them:

For a transfer signed by a delegated key, every one of these is evaluated against the parent account. A payload describing the agent will fail the registry checks.

The gate trace

When raw_log is not enough, ask for the gate-by-gate record:

curl -s "$REST/hkchain/compliance/v1/tx_trace/<TXHASH>"

Each row is one gate: its name, BLOCKING or ADVISORY, a status, a reason, and gas consumed. Statuses are PASS, FAIL, FLAGGED. The top-level accepted is true only when every blocking gate passed — an advisory FLAGGED does not flip it.

Reasons are written for a compliance reader, with a stable prefix per gate:

Advisory gates carry a fixed label instead — Reviewer flag: transfer at or above HKD 8,000 threshold, Reviewer flag: transfer-density burst inside rolling window. A FLAGGED row means a human will look at the transfer, not that anything failed.

A rejected transaction still has a trace: the rows up to and including the failure are recorded before the error propagates.

When the trace is gone

Traces are held in memory on the node that ran the transaction — 256 entries, one hour, whichever comes first — and are not chain state. When the lookup misses, re-run the same bytes through simulation:

curl -s -X POST "$REST/hkchain/compliance/v1/simulate_trace" \
  -H 'Content-Type: application/json' \
  -d '{"tx_bytes":"<base64 signed tx>"}'

The response has the same shape with simulated: true. It runs against current state on a discarded copy, so it answers "what would happen now", which is the same answer as long as nothing relevant changed.

Simulation is also the right pre-flight check: run it before broadcasting and a rejection costs you no round trip at all. Two limits on it:

• It decodes a Cosmos transaction. The bytes are decoded with the chain's transaction decoder and the gates run over the messages found inside. It is not an EVM call simulator: pointing it at an Ethereum transaction does not execute the call, so it cannot report on a transfer made through the ERC-20 interface. The pre-flight check for that path is a read-only eth_call of the same method with the same arguments, which runs the gates and returns the revert reason without submitting anything.
• It requires the module's simulation hook to be wired at node start-up. A node that has not wired it answers with a configuration error rather than a trace.

Module errors

Errors raised while a message executes. These are execution failures — the transaction is in a block.

stablecoin

kyc

reserve

compliance — beyond the gate errors above

Sequence collisions

Two transactions signed at the same sequence: the first is admitted, the second is rejected. This does carry a code, and knowing which one saves an investigation:

It arrives from the signature-verification stage, so a client that classifies by stage rather than by code reports it as a signature problem — which is misleading, because the signature was fine and the sequence was not. Branch on sdk/32 and read the expected and received numbers out of raw_log; they tell you exactly how far your local counter has drifted.

Track sequence locally when you submit in parallel; the account query reflects committed state and lags anything you have already broadcast.

The failure with no code at all

A transaction that never lands. The broadcast returned 0, so it was admitted somewhere, but the hash does not resolve and no error is ever produced. There is nothing to read: an admitted transaction can sit in a mempool indefinitely, and it can equally be dropped from one — evicted when the mempool fills, aged out, or lost when the node restarts — without notifying anyone.

Treat this as a state your integration owns rather than one the chain will resolve for you: after a reconciliation window of your choosing, declare the hash not landed and re-sign at the same sequence. See Broadcasting and confirmation for the polling shape.

EVM-side failures

A compliance rejection on the EVM path becomes a revert, with the gate's error carried up verbatim as the revert reason. The same causes and the same messages reach you, in an Ethereum-shaped envelope.

The envelope is the part to get right. A revert is not a rejected submission: eth_sendRawTransaction returns a hash, the transaction is mined, and the receipt records the failure as status: 0x0. The reason is not in the receipt — it is in the call's revert data, which an Ethereum receipt has no field for. An eth_call with the same arguments returns it: a JSON-RPC error, code 3, execution reverted: <the gate's message>.

A gate trace is still recorded for an EVM-originated transfer, but it is keyed by the Cosmos transaction hash of the wrapping transaction — not by the Ethereum transaction hash your tooling reports.

Vanilla transfer and transferFrom revert unconditionally, before anything else runs:

HKCHAIN: vanilla transfer disabled — use transferWithTravelRule
HKCHAIN: vanilla transferFrom disabled — use transferFromWithTravelRule

If an ERC-20 library reports an unexplained revert on a transfer that looks correct, this is almost always it: the library called the standard method.

Where to go next

• Events and indexing — the durable record of what did happen.
• Integration patterns — where to put these checks in a real system.