Rate limits - AroPay

Limits are generous for real integrations and tight enough to blunt abuse.

The numbers

Scope	Limit	Window
Login attempts	10	15 minutes per IP
Write requests (POST/PATCH/DELETE)	30	1 minute per principal
Read requests (GET)	120	1 minute per principal
Account lockout	after 5 consecutive failed logins	15 minutes
Faucet volume	deployment-configured cap	rolling 24 h per account

A principal is whoever authenticated: a given API key and a browser session count separately, but all keys of one account share its account-level protections.

When you exceed a limit

The API returns 429 with the standard envelope:

{
  "ok": false,
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Try again shortly."
  }
}

Back off and retry. A simple pattern with jitter:

attempt=0
until out=$(curl -sf "$BASE/balances" -H "Authorization: Bearer $KEY"); do
  attempt=$((attempt+1))
  [ $attempt -ge 5 ] && { echo "giving up" >&2; exit 1; }
  sleep $(( (2 ** attempt) + RANDOM % 3 ))
done
echo "$out"

Staying well under the limits

Poll gas, not balances. GET /gas is designed for polling; /balances does FHE work. See Balances.
Poll transactions at 3–10 s intervals; faster adds no information (Sepolia blocks land every ~12 s) and burns read budget. See Track transactions.
Paginate deliberately. pageSize goes up to 100; one big page beats five small ones.
Money movement already blocks up to ~90 s waiting for receipts, so don’t wrap it in a hot retry loop; on PENDING, switch to polling the transaction.

Lockout behavior

Five consecutive failed logins lock the account for 15 minutes; even correct credentials are refused until the window passes. Failed-attempt counters reset on successful login. Locked-out or disabled states are not distinguishable from bad credentials in the login response (deliberately), so surface the generic failure to end users.

⌘I