Rate Limiting & Abuse Prevention

Rate limits are SohoPay’s abuse-prevention layer and your loss-bounding layer: they cap how fast an agent can spend, how much load a merchant can aggregate, and how hard anyone can hit the API. This page covers all three tiers, the correct client behavior on a 429, and how to get limits raised.

The three tiers of limits

Tier	What’s limited	Set by	Enforced by
Per-agent	Payments per hour, and USDC per day via `daily_limit`	You, at agent creation (adjustable via `PATCH /agents/{id}`)	Policy Service, on every payment
Per-merchant	Aggregate payment throughput across all agents paying one merchant	SohoPay, based on merchant tier	Policy Service
API requests	HTTP requests per key per minute	SohoPay	API gateway

Per-agent limits are your primary risk control. daily_limit caps USDC spent per rolling 24 hours; the payments-per-hour cap prevents a runaway loop from draining the daily limit in seconds. A payment that would exceed either is rejected — it never reaches settlement. Per-merchant aggregate limits protect merchants and the network from a single merchant absorbing abusive volume across many agents. If your legitimate volume approaches your merchant tier’s ceiling, appeal below — don’t shard across shell merchants, which violates the Terms of Service. API request limits apply to all endpoints and are separate from payment limits: reads (polling payments, listing agents) count against them even though no money moves.

What a rate-limited response looks like

Exceeding any tier returns HTTP 429 with error code RATE_LIMITED, a Retry-After header (seconds), and the standard rate-limit headers on every response:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Agent agt_7d1e5b2f has reached its hourly payment limit. Retry after 1140 seconds.",
    "request_id": "req_c3d9f0a1"
  }
}

Header	Meaning
`X-RateLimit-Limit`	Your total allowance in the current window
`X-RateLimit-Remaining`	Requests (or payments) left in the window
`Retry-After`	Seconds to wait before retrying (on `429` responses)

Watch X-RateLimit-Remaining on successful responses and slow down before you hit zero. Reacting only to 429s means your busiest moments are also your most error-prone.

Backoff strategy

On 429, honor Retry-After when present; otherwise use exponential backoff with jitter so a fleet of agents doesn’t retry in lockstep:

async function withBackoff<T>(fn: () => Promise<T>, maxRetries = 5): Promise<T> {
  for (let attempt = 0; ; attempt++) {
    try {
      return await fn();
    } catch (err: any) {
      if (err.status !== 429 || attempt >= maxRetries) throw err;
      const base = err.retryAfter // from Retry-After header, in seconds
        ? err.retryAfter * 1000
        : Math.min(1000 * 2 ** attempt, 60_000);
      const jitter = Math.random() * base * 0.25;
      await new Promise((r) => setTimeout(r, base + jitter));
    }
  }
}

Pair retries with the Idempotency-Key header on POSTs so a retry can never double-submit a payment — see Error Handling.

Worked example: hitting the daily limit mid-day

An agent has daily_limit: "100.00" and makes a 4.00 USDC purchase roughly every 30 minutes.

00:00–12:30 — 25 payments settle normally, 100.00 USDC spent. X-RateLimit-Remaining on the payment scope reads 0.
13:00 — payment 26 is rejected with 429 RATE_LIMITED and Retry-After: 39600 (11 hours: when the earliest spend rolls out of the 24h window). No settlement occurs, no fee is charged.
Correct behavior — the agent parks the task and schedules a retry for after the window resets, rather than hammering the endpoint. Your ops team sees the 80%-of-daily-limit alert from Wallet Usage Analytics hours earlier, at 10:00, and can decide whether to raise the limit before it bites.
If this was legitimate demand — raise daily_limit via PATCH /agents/{id} (up to your account ceiling) or file an appeal.

Appealing a limit

If a SohoPay-set ceiling (per-merchant aggregate, API request rate, or your account’s maximum daily_limit) is too low for real traffic:

Email support@sohopay.xyz with subject “Rate limit increase”, the agent or merchant ID, current vs. requested limit, and a sentence on the use case driving the volume.
Include 7+ days of real traffic (a Wallet Usage CSV export works) — increases are granted on demonstrated legitimate usage.
Normal-priority response applies: under 8 hours per the support SLA. Increases usually take effect within 1 business day of approval.

Sandbox limits are intentionally low and are not raised — they exist so you can test 429 handling cheaply. See Testing for forcing rate-limit responses on demand.

Next steps

Error Handling

Retries, idempotency keys, and the full error-code catalogue.

Operator Liability

Why tight limits are your best defense against a compromised agent.

Wallet Usage Analytics

Alerts that warn you before an agent hits its ceiling.

Getting Started

Merchant Integration

Agent Wallet Setup

Payment Flow

Protocol & Standards

Compliance & Risk

Operational Dashboards

Rate Limiting & Abuse Prevention

The three tiers of limits

What a rate-limited response looks like

Backoff strategy

Worked example: hitting the daily limit mid-day

Appealing a limit

Next steps

Error Handling

Operator Liability

Wallet Usage Analytics

​The three tiers of limits

​What a rate-limited response looks like

​Backoff strategy

​Worked example: hitting the daily limit mid-day

​Appealing a limit

​Next steps

Error Handling

Operator Liability

Wallet Usage Analytics

The three tiers of limits

What a rate-limited response looks like

Backoff strategy

Worked example: hitting the daily limit mid-day

Appealing a limit

Next steps