Falcon errors & retries

The same rejection looks completely different depending on how you submitted it.

JSON-RPC errors

Falcon answers with HTTP 200 for almost every JSON-RPC error. Only two carry a matching status.

-32602 messages

-32002 carries the whole simulation result in data, including err, logs and unitsConsumed.

Raw HTTP errors

/binary and /plaintext answer with a status and a short plain-text body. Several causes share a status, so the body is the only thing that separates them.

No HTTP route reports a forwarding failure. Once validation passes you get 200 and a signature, whatever the forward does.

QUIC rejections

Server rejections reach you as a SubmitError. On the wire that's two bytes: 0x01, then the code.

use falcon_client::SubmitError;

match client.send_transaction(&transaction).await {
    Ok(()) => {}
    Err(error) => match error.downcast_ref::<SubmitError>() {
        Some(SubmitError::RateLimited) => {
            // Back off, then resubmit the same signed bytes.
        }
        Some(rejection) => {
            // Permanent: fix the transaction.
            eprintln!("falcon rejected the transaction: {rejection}");
        }
        None => {
            // Transport-level: timeout, MTU, connection lost.
            eprintln!("falcon transport error: {error}");
        }
    },
}

An Err with no SubmitError inside is a transport problem rather than a rejection, and by the time you see it the SDK has already reconnected and retried once.

Connection-level failures

When the server closes the QUIC connection, it gives you a readable reason:

Individual streams also get reset when one connection has too many in flight at once; cap your concurrent sends rather than opening more connections.

Native UDP

Native UDP has no error surface at all. Bad frame, bad key, oversized transaction, missing tip, forward failure: every one is the same silence. The full drop list is on Native UDP.

Retry decision table

Stop on blockhash expiry rather than on an attempt count.

Duplicates

Falcon keeps a signature-keyed cache of recent submissions and short-circuits a duplicate instead of forwarding it again. That only takes effect after a submission of that signature has been delivered, so a copy arriving while the first is still in flight is forwarded too. That's why resending the same signed bytes to chase a landing is expected behaviour. Delivery still isn't exactly-once in either direction.

Acceptance is not landing

Falcon's answer never depends on the outcome of the forward, on any transport.

Record both sides. Telemetry has the fields to keep.