Rate limits and quotas: what actually bounds your traffic

What bounds your traffic

There are no usage tiers to climb, no per-account throughput grade, and nothing that unlocks after a spending threshold. Every account gets the same treatment from its first request.

What bounds you is three things: whether your wallet has money in it, whether the individual key has a quota ceiling set on it, and — for two specific model ids — how many of your requests are in flight at once.

Every model is served from the shared account pool. When every pool account that can serve a model is busy at that moment, the request returns 429 with a Retry-After saying when capacity is expected back.

Balance and per-key quota

Before a request is forwarded, the gateway resolves which wallet will pay for it. An auto key walks recharge balance, then earned credit, then promotional balance, taking the first with money in it; a key pinned to one wallet is checked against that wallet alone. No spendable wallet means 403, with a message naming which balance is empty.

A key can also carry its own quota ceiling, independent of the account balance. Exhausting it returns 402 "api key quota exceeded" — useful for capping a single service or a single environment without touching the rest of the account.

One funding rule is specific rather than general: Claude ids draw only on the recharge wallet, returning 402 claude_minimum_balance otherwise.

#!/usr/bin/env bash
set -euo pipefail

for attempt in 1 2 3 4 5; do
  status=$(curl -sS -o /tmp/resp.json -D /tmp/resp.headers -w '%{http_code}' \
    https://token-share.app/v1/messages \
    -H "x-api-key: $TOKEN_SHARE_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-sonnet-5",
      "max_tokens": 256,
      "messages": [{"role": "user", "content": "ping"}]
    }')

  if [ "$status" != "429" ] && [ "$status" != "503" ]; then
    cat /tmp/resp.json
    exit 0
  fi

  # Honour Retry-After when present; otherwise back off exponentially.
  wait=$(awk 'tolower($1) == "retry-after:" { print $2 }' /tmp/resp.headers | tr -d '\r')
  sleep "${wait:-$((2 ** attempt))}"
done

echo "gave up after 5 attempts" >&2
exit 1

Concurrency on two model ids, and how spending is counted

Two ids carry a per-model concurrency cap: claude-sonnet-5 and gpt-5.6-luna. They handle a full lane differently. A Sonnet request that arrives with no free slot waits in a FIFO queue and is admitted when one frees up; if it is still waiting after 30 seconds it returns 429 model_queue_timeout. A Luna request that arrives with no free slot is refused immediately with 429 model_capacity_exceeded and Retry-After: 1, rather than being queued.

That difference is a trade, not a ranking. Queueing turns a burst into latency, which suits a batch job that would rather wait than retry; failing fast turns it into an immediate error, which suits an interactive caller that would rather retry than sit on a stalled connection. Neither is the correct behaviour in general — it depends on whether your caller can afford to wait.

Spending is deducted after a request completes, not reserved before it. The pre-flight check only asks whether the wallet is non-empty, so a burst of concurrent requests against a nearly empty balance can carry it past zero; the resulting shortfall is recorded rather than silently absorbed. A billed request is charged at least $0.0001, so a trivially small call is not free. Claude ids carry a higher floor of $0.001, because even a trivial Claude call occupies a pool account for a full round trip.

Common questions