Rate Limits and Errors

Venues limit how fast you send. Break a limit and they refuse requests; keep going and they ban your IP. ergon-io checks each request against the limits before it goes out, and tells you what became of it after.

• It never sleeps, queues or retries. You decide: wait, drop or alert.
• No venue tables in the published crate: venues change them without notice. Binance, Bybit and OKX adapters live in the repository’s io/examples/venues.rs.

What venues do

Checked 2026-10-17 against each venue’s docs (linked). Values change: load them at start where the venue publishes them (Binance exchangeInfo). Where a number is not on the linked page, the source is named in the cell.

• One order counts against several limits at once: a Binance order against IP weight, raw requests, orders per 10 s and orders per day.
• Errors often come as HTTP 200 with a code in the body (Bybit, OKX). Classify on status and code.
• WebSocket limits count control frames (Binance spot: 5 messages/s, Pongs included) and connect attempts per IP (Binance 300/5 min, OKX 3/s).
• HTTP status is not the code. The same body code can arrive with 200, 429 or another status: read the code.

What ergon-io gives you

One order, start to end

A Binance adapter: limits at start, the charge before sending, the verdict after:

    // At start: Binance's limits from `GET /api/v3/exchangeInfo`.
    let limits = binance::limits(example::BINANCE_EXCHANGE_INFO.as_bytes())?;
    let (b, mut budget) = binance::Binance::new(limits)?;
    // Before sending: every bucket the order counts against, or none.
    let ticket = budget.try_charge(b.new_order()?.as_slice(), Class::Normal, T0)?;
    // On its response (`on` replays a recorded one): usage, then the verdict.
    let v = on(example::BINANCE, "order-ack", |r| {
        b.on_response(r, &mut budget, NOW)
    })??;

What it reads in a response:

            match r.status {
                // Bans (403: the WAF limit, 418): the IP scope stops until a
                // person clears it. Before any header: a ban always halts.
                // The gate every request and every connect charges, so one
                // ban stops them all.
                403 | 418 => return super::ban(r, self.ip, BAN_MIN_MS, budget, now),
                _ => {}
            }
            let code = match super::json_body(r)? {
                Some(body) if r.status >= 400 => {
                    body.get("code")?.map(json::Value::as_i64).transpose()?
                }
                _ => None,
            };
            // 409 cancel-replace: -2022 ran nothing (both halves failed);
            // -2021 may have run one half.
            if r.status == 409 {
                return Ok(match code {
                    Some(-2022) => Verdict::NotRun,
                    _ => Verdict::Unknown,
                });
            }
            let verdict = match code {
                Some(-1003) => {
                    // "Too many requests queued." is a queue depth, not the
                    // weight window: filling the weight bucket would stop
                    // everything on the IP for a whole window. The queued
                    // variant holds the raw-requests scope, else a short hold
                    // on weight that does not fill it.
                    if super::contains_ignore_case(r.body, b"queued") {
                        if let Some(raw) = self.raw {
                            super::throttle(r, raw, budget, now)
                        } else {
                            let wait = outcome::retry_after_ms(r, super::utc_ms(now))?.or(Some(0));
                            let until_ns = budget.throttled(self.weight, wait, now.ns)?;
                            Ok(Verdict::Throttled {
                                bucket: self.weight,
                                until_ns,
                            })
                        }
                    } else {
                        super::throttle(r, self.weight, budget, now)
                    }
                }
                Some(-1015) => self.too_many_orders(r, budget, now),
                Some(-1021) => Ok(Verdict::ClockSkew),
                // -1006, -1007 and -1008: -1006/-1007 lost track of the
                // request; spot -1008 is only "server is currently
                // overloaded" and does not say the order failed. All three
                // mean it may have run.
                Some(-1008..=-1006) => Ok(Verdict::Unknown),
                // Status alone: 2xx done, 429 throttled, 4xx rejected, 5xx unknown.
                _ => outcome::generic(r, self.weight, budget, now),
            }?;
            // Server truth, after the hold or halt stands: other senders on
            // this IP or account show up here. A malformed usage header is
            // reported but does not undo the hold.
            for (name, bucket) in &self.usage {
                if let Some(used) = super::usage(r, name)? {
                    budget.observe_used(*bucket, used, now.ns)?;
                }
            }
            Ok(verdict)

What to do next with the order:

/// The re-send rules: only what did not run, through the budget, inside
/// its own deadline; never an order that may have run.
///
/// [`Budget::resend`] makes that last rule structural: it answers
/// `Reconcile` for an unknown outcome instead of a re-send.
#[must_use]
pub fn next(order: &Order, verdict: Verdict, budget: &mut Budget, now_ns: i64) -> Next {
    match verdict {
        Verdict::Done => Next::Applied,
        Verdict::Rejected => Next::Dropped,
        Verdict::Banned { bucket, .. } => Next::Halted(bucket),
        _ => match budget.resend(
            verdict,
            order.parts.as_slice(),
            order.class,
            order.deadline_ns,
            now_ns,
        ) {
            Resend::Send(ticket) => Next::SendNow(ticket),
            Resend::Wait(limited) => Next::RetryAt(limited.ready_at_ns),
            Resend::Stale(_) => Next::Dropped,
            Resend::Reconcile => Next::Reconcile(order.client_order_id),
        },
    }
}

(From io/examples/venues.rs and io/tests/example_venues.rs, which cargo test -p ergon-io runs on every platform against responses written from each venue’s docs, in io/tests/fixtures/venues/. cargo run -p ergon-io --example venues prints each decision.)

Over the wire, one order with the pooled client:

1. try_charge → keep the Ticket by request id.
2. HttpClient::request returns at once; the answer comes to ClientHandler::on_response or on_error.
3. on_response → the adapter’s on_response above, then Budget::resend for the verdict.
4. on_error(request, sent, error) → Sent::No: refund the ticket and Budget::resend; Sent::Maybe: Unknown, reconcile by client order id.

Error policy

• A timeout is not a free re-send. A 408, and a Binance -1007 (“timeout waiting for response from backend server”), are Unknown: the backend may have taken the order. Re-send only what the venue says did not run (a Binance -2022), never what might have.
• The code decides before the status. On a 409 the body code picks NotRun (-2022) or Unknown (-2021).
• Hold the narrowest bucket the error names. A -1015 for 10 s holds the 10 s order bucket; cancels (not orders) still go.
• A hold blocks cancels too. On Binance a request sent into a 429 risks a ban. Arm the venue’s cancel-on-disconnect before trading: it is the only cancel path during a hold.
• Refund only Sent::No and Busy. Venues count rejected and throttled requests too.
• A server wait is the server’s answer. A 429 with Retry-After holds for that wait plus the guard; the bucket keeps its count. With no wait, the bucket is marked full for one window (the local count was wrong).
• A ClockSkew that repeats is the host clock. Re-signing with a new timestamp fixes one; if they keep coming, the clock is off: fix the host clock (chrony; see Clocks), not the re-send.

Rules

1. A ban stops sending until a person clears it. Budget::banned halts the scope. The end of the venue’s wait does not resume it: Budget::clear_halt, called by a person’s action, does. Budget::halted() and BucketStats::halted show it, so the loop can alert. Halt an IP-scope gate that every request and every connect charges, so one ban stops them all. The minimum waits differ: Binance 418 is 2 minutes (to 3 days for repeats); Bybit 403 is 10 minutes. A second ban costs more than a pause.
2. One sender per account and IP. The budget sees only this process. Budgets are not shared between processes.
3. Send again only what did not run, and only inside its deadline (Throttled, ClockSkew, NotRun). The application sets each order’s deadline (a few ms, say). Budget::try_resend charges it again, or says when to ask, or calls it stale.
4. Never send an order with an unknown outcome again. Every order carries a unique client order id; look it up by that id (or watch the user data stream). Only Coinbase Advanced Trade returns the existing order for a repeated id.
5. libcurl takes no method but GET, HEAD, OPTIONS and DELETE unless you opt in (below).

A ban, step by step:

    let v = on(example::BINANCE, "ban-418", |r| {
        b.on_response(r, &mut budget, NOW)
    })??;
    // Retry-After 300 s. The IP gate has no window to align to, so no
    // guard: this is the end of the server's wait. The halt does not end
    // there; a person clears it.
    assert_eq!(
        v,
        Verdict::Banned {
            bucket: b.ip(),
            until_ns: T0 + 300 * S
        }
    );
    // Ten minutes later the server's wait is long over: still stopped.
    let later = T0 + 600 * S;
    assert_eq!(why(&mut budget, &b.request(1)?, later), Some(Why::Banned));
    // Every connect is stopped too: it charges the same gate.
    assert_eq!(
        why(&mut budget, &b.connect(), later),
        Some(Why::Banned),
        "a banned IP must not reconnect"
    );
    // The loop's alert check names it.
    let mut alerted = Vec::new();
    example::alerts(&budget, later, |name, stats| {
        alerted.push((name.to_owned(), stats.bans));
    })?;
    assert_eq!(alerted, [("ip".to_owned(), 1)]);
    // A person decides; then sending resumes.
    budget.clear_halt(b.ip())?;
    assert_eq!(why(&mut budget, &b.request(1)?, later), None);
    assert_eq!(why(&mut budget, &b.connect(), later), None);

What it cannot do

• See other senders. The venue counts every process, host behind the same NAT and script on the same key or IP. Usage headers show them late (one round trip) and only in part; Kraken, Coinbase, Deribit and OKX send none. So run one sending process per account and IP. Put bulk REST on another IP, or in the same process and budget.
• Know a WebSocket request’s fate when its connection drops: ergon-io does not know WebSocket request ids. Treat pending ones as unknown.
• Retry or queue. Only the application knows whether a request is still wanted, and it must sign it again with a new timestamp.

libcurl sends requests twice

• What happens: when a reused connection dies before any reply byte, libcurl sends the request again, POST included, up to 5 times (Curl_retry_request in lib/transfer.c, curl 8.22.0). No option turns this off. An order that ran just before the connection died runs twice.
• What ergon-io does: the libcurl HttpClient refuses every method but GET, HEAD, OPTIONS and DELETE, with Error::CurlResend, unless curl_allow_non_idempotent_methods is set. io/tests/client.rs shows libcurl re-sending, and the refusal.
• Send orders through the native client: it never re-sends.

Cost

try_charge, the check before each request, is on the send path. Its cost is not measured here: no committed run holds it. Measure it with io/benches limit_bench:

cargo build --release --manifest-path io/benches/Cargo.toml --bin limit_bench
io/benches/target/release/limit_bench --samples 200000 --batch 64   # Linux: --cpu <isolated cpu>

• The bench reports ns per call (the mean of a --batch-call batch, not a per-call percentile), the slowest batch, stalls and allocs (allocations in the timed loop; expect 0).
• Catch-up walk. A ring stepped just under one full turn walks every slot instead of taking the fill(0) path a longer idle would. Budget::tick during idle keeps this off the send path: the send path only ever pays for the slots since the last charge.
• macOS cannot pin or isolate the thread; a quiet max needs an isolated Linux CPU.
• Inside ergon-io the send path adds one store per request and one add per send (for Sent), and one add per automatic WebSocket frame.