TESTNET
Connect

Rate limits

Polyester rate-limits trading, account, security, and money-movement operations with weighted pools. REST, ConnectRPC, and trade WebSocket aliases for the same action share one quota.

Pools refill continuously. Capacity returns gradually; it does not reset on a fixed minute or hour boundary.

Concept Meaning
Pool Shared unit bucket. Same string as policy_class in rejection responses.
Sustained rate Refill speed, for example 120 units/min.
Burst capacity Max units a full pool can spend immediately.
Cost Units charged for one request or admitted batch item.

Defaults below can be overridden per account or API key. GET /v1/rate-limits (GetRateLimitConfig) returns the active public VIP0-VIP10 placement and cancellation catalog. Authenticated clients can call GET /v1/trading/rate-limits (GetTradingRateLimits) to resolve the effective limits for their Main Account or an accessible Subaccount. Without subaccountId, a Subaccount-scoped API key resolves its bound Subaccount. API-key callers receive both the account-scoped and API-key-scoped rules because both scopes are enforced.

Right after a policy is created for or attached to a Subaccount, a Subaccount request can briefly fail with a retryable unavailable error (HTTP 503) while the new policy takes effect. Retry with backoff for a few seconds. A permission denial (HTTP 403) remains final.

These endpoints return policy configuration, not live remaining capacity. Response headers and rejection details remain authoritative for current usage and retry timing.

Limits by pool

Each pool lists its unit capacity and scopes, then the operations that spend from it. A blank Pool cell means the row shares the pool above. Sustained and burst already include cost.

Same pool = shared capacity. Extra API keys do not add capacity. Any exhausted scope rejects the request.

Authentication and account management

Pool Capacity Scopes
AUTH_PUBLIC 30 units/min · burst 30 CLIENT_IP, AUTH_SUBJECT
ACCOUNT_ADMIN 120 units/min · burst 30 ACCOUNT, API_KEY, SUBACCOUNT
ACCOUNT_SECURITY 60 units/min · burst 20 ACCOUNT, API_KEY, SUBACCOUNT
SOCIAL_PROVIDER 10 units/hour · burst 3 ACCOUNT, API_KEY, SUBACCOUNT
Pool Operation Cost and limit
AUTH_PUBLIC Wallet nonce or login 1 unit · 30 req/min · burst 30 req
ACCOUNT_ADMIN Profile, Subaccount, member, invite, or address-book mutation 2 units · 60 req/min · burst 15 req
ACCOUNT_SECURITY MFA challenge or step-up 1 unit · 60 req/min · burst 20 req
Access-policy, MFA enrollment, or MFA factor mutation 2 units · 30 req/min · burst 10 req
API key create, update, or delete; recovery-code regeneration 5 units · 12 req/min · burst 4 req
SOCIAL_PROVIDER Start external social verification 1 unit · 10 req/hour · burst 3 req

AUTH_PUBLIC is dual-scoped: client IP and wallet subject (AUTH_SUBJECT). Hitting either limit rejects the request.

Deposits, withdrawals, and internal transfers

Pool Capacity Scopes
DEPOSIT_CREATE 10 units/min · burst 3 ACCOUNT, API_KEY, SUBACCOUNT
INTERNAL_TRANSFER 60 units/min · burst 10 ACCOUNT, API_KEY, SUBACCOUNT
WITHDRAW_SUBMIT 10 units/min · burst 5 ACCOUNT, API_KEY, SUBACCOUNT
WITHDRAW_VALIDATE 120 units/min · burst 30 ACCOUNT, API_KEY, SUBACCOUNT
Pool Operation Cost and limit
DEPOSIT_CREATE Create a deposit address 1 unit · 10 req/min · burst 3 req
INTERNAL_TRANSFER Create an internal transfer 1 unit · 60 req/min · burst 10 req
WITHDRAW_SUBMIT Submit a trading withdrawal 1 unit · 10 req/min · burst 5 req
WITHDRAW_VALIDATE Validate a withdrawal destination 1 unit · 120 req/min · burst 30 req

WITHDRAW_SUBMIT: 5 immediate when full, then one every six seconds. Long-term: 10/min.

GuardSigner

Pool Capacity Scopes
GUARD_SIGN 300 units/min · burst 100 ACCOUNT, API_KEY, SUBACCOUNT
Pool Operation Cost and limit
GUARD_SIGN Create a wallet or sign a protected action 5 units · 60 req/min · burst 20 req
Batch sign protected actions 5 units/item · 60 items/min · burst 20 items
Rotate or export a GuardSigner wallet 10 units · 30 req/min · burst 10 req

Trading

Placement and cancellation are separate pools per trading account (Main Account or Subaccount). All keys and transports for that account share those pools. Limits are account-wide across symbols: BTC and ETH orders draw from the same placement pool. Placement exhaustion does not reduce cancellation capacity. Replaying an already admitted trading request with the same idempotency key does not charge again.

Scopes for both pools: ACCOUNT, API_KEY, SUBACCOUNT. Batch rows charge per admitted item; other rows charge per request. Place and cancel columns are TRADING_PLACE and TRADING_CANCEL weighted capacity from the public catalog.

VIP 0
250/s
500
500/s
1,000
VIP 1
500/s
1,000
1,000/s
2,000
VIP 2
1,000/s
2,000
2,000/s
4,000
VIP 3
2,500/s
5,000
5,000/s
10,000
VIP 4
2,500/s
5,000
5,000/s
10,000
VIP 5
2,500/s
5,000
5,000/s
10,000
VIP 6
2,500/s
5,000
5,000/s
10,000
VIP 7
2,500/s
5,000
5,000/s
10,000
VIP 8
2,500/s
5,000
5,000/s
10,000
VIP 9
2,500/s
5,000
5,000/s
10,000
VIP 10
2,500/s
5,000
5,000/s
10,000
Operation Cost
Place: create, modify, resume 1
Place: batch create/replace 1/item
Cancel: single, pause, CancelAllAfter 1
Cancel: batch 1/item
Cancel all 10

Sustained and burst for each operation are the VIP catalog quota divided by that cost. Higher professional or market-maker capacity requires an account-specific override and is not granted automatically by retail VIP status.

Read and realtime quotas are not published yet. Other ingress and abuse controls can still reject requests outside these pools.

Concurrent order requests

An account can also reach its limit of outstanding order requests. This rejects the request with OVERLOADED before admission: ConnectRPC returns resource_exhausted (HTTP 429), and REST returns HTTP 503. These responses carry no Retry-After, RateLimit-*, or X-Polyester-RateLimit-Policy-Version headers and no quota details. Retry after an outstanding request completes. Quota exhaustion uses the separate rejection contract below.

Venue and gateway limits

These refusals do not mean your account's quota is exhausted:

  • SYSTEM_RATE_LIMITED
    The venue-wide admission rate shared with other accounts is exhausted. ConnectRPC resource_exhausted, REST 429. Retry shortly with backoff.
  • RATE_LIMIT_POLICY_UNAVAILABLE
    No usable rate-limit policy applies to the account right now, so the request is refused rather than admitted without a limit. ConnectRPC unavailable, REST 503. Retry later.
  • Plain HTTP 429, no Polyester body
    The per-IP limit on REST and ConnectRPC order and trigger writes, about 10,000 requests per second from one IP address. A batch counts as one request. Back off and retry.

The per-IP refusal carries no Retry-After header. Reads and the trade WebSocket's commands are not counted against it.

Rejection contracts

policy_class in the error is the pool name (WITHDRAW_SUBMIT, ACCOUNT_SECURITY, …).

Quota exceeded: HTTP 429 with application/problem+json.

Header Meaning
RateLimit-Limit Active weighted limit for the rejected pool
RateLimit-Remaining Remaining capacity at rejection
RateLimit-Reset / Retry-After Seconds until a retry may succeed, rounded up
X-Polyester-RateLimit-Policy-Version Policy version used

Body includes millisecond precision:

{
	"type": "https://polyester.dev/problems/rate-limit-exceeded",
	"title": "Rate limit exceeded",
	"status": 429,
	"detail": "Rate limit exceeded",
	"code": "RATE_LIMIT_EXCEEDED",
	"rate_limit": {
		"reason": "QUOTA_EXCEEDED",
		"limit": "10",
		"remaining": "0",
		"retry_after_ms": "6000",
		"policy_version": "3",
		"operation_id": "withdraw.submit",
		"policy_class": "WITHDRAW_SUBMIT",
		"scope": "ACCOUNT",
		"refill_model": "CONTINUOUS"
	}
}

uint64 fields are JSON strings. scope is which dimension rejected the call: CLIENT_IP, AUTH_SUBJECT, API_KEY, ACCOUNT, or SUBACCOUNT.

Retry on 429

For 503 / RATE_LIMIT_AUTHORITY_UNAVAILABLE, see Authority failures.

Wait

Use retry_after_ms if present, else Retry-After. Add a little jitter.

Keep the same request

Keep replayable idempotency keys and payloads unchanged. For a single-order create, preserve the client order ID for reconciliation. If that ID was already retained, resubmission returns CONFLICT_DUPLICATE_CLIENT_ORDER_ID instead of replaying the earlier result.

Re-sign API keys

Fresh timestamp and signature on each retry.

Stop eventually

Do not hammer a rejected batch or instantly fan it into many single requests.

See Client order IDs and idempotency.

Authority failures

Order types and lifecycle Order types, time in force, statuses and their transitions, cancel and reject reasons, versions, modify and replace, and how to read orders and fills. Fills and trade history Read your executions, reconcile order totals and fees, and backfill a durable trading history. Order sizing Choose exact base-quantity or maximum quote-debit sizing and read the authoritative quantity accepted for execution. Client order IDs and idempotency Use client order IDs to prevent duplicate placement, correlate client intents, and reconcile uncertain outcomes. Preview order Check whether an order is currently admissible without creating an order, reserving funds, or presenting an execution quote. Market order price protection Understand market-order slippage overrides, Pair defaults, client reference drift, execution boundaries, and stale-quote errors. Self-trade prevention Prevent an incoming order from trading against a resting order of the same Main Account or its Subaccounts. Batch orders Create, replace, or cancel many orders in one request, read each item's result, and retry safely after a partial failure or an unknown outcome. Cancel all orders Cancel every open order that matches a filter, with an answer at acceptance and idempotent retries. Dead-man switch Arm a heartbeat timer with CancelAllAfter so your open orders are canceled automatically if your system stops refreshing it. Fee Assets Choose whether a BUY fee is charged in quote or deducted from received base, and decode fee amounts with the correct scale. Swap Convert Trading balances through spot order books with quotes, minimum output protection, and idempotent execution. Triggers overview How standalone and attached triggers watch a price or a schedule, place child orders, report their status, and count against limits. WebSocket session model Understand shared connection, authentication, subscription, and recovery behavior for Polyester realtime channels. Recover after reconnect Rebuild a bot's orders, executions, balances, and triggers after a disconnect or restart without duplicating orders. Public IDs Understand what Polyester public IDs identify, why they are opaque, and how their representation differs per interface.
Previous

Attached take-profit and stop-loss
Next

WebSocket session model