# Rate Limiting for Virtual Accounts

Endpoints that involve **`virtual-accounts`** have a few extra rules on top of the standard API limits. These rules help us keep downstream systems stable and ensure that every client gets fair access.

## What’s in Scope?

* **Endpoints affected**: Anything with `virtual-accounts` in the path.
Example: `POST …/virtual-accounts` (for creating a new account).
* **How requests are counted**:
  * We apply a **global pacing rule** for **account creation**.
  * This means **all clients together** share one pool.
  * Limit: **1 request every 2 seconds (global)**.


👉 Important: There’s no extra per-client cap for creating accounts. The usual API-wide limits still apply separately.

## The Limits

| What’s Limited | Applies To | Limit | What Happens If You Go Over |
|  --- | --- | --- | --- |
| **Global pacing** | `virtual-accounts` **creation** (all clients combined) | **1 request every 2 seconds** | Requests above the limit are automatically queued or throttled. If they can’t be served in time, you’ll get a `429 Too Many Requests`. |


## What Happens if You Hit the Limit?

If you send requests too quickly, you’ll get back an **HTTP 429 Too Many Requests** response with guidance on when to try again.

**Example response**


```json
{
  "error": "Virtual accounts global rate limit exceeded",
  "message": "Only one virtual-accounts request is allowed globally per 2 seconds. Please wait and retry.",
  "rate_limit_type": "global_virtual_accounts",
  "retry_after": "2 seconds"
}
```

## Quick Tips

* Treat `retry_after` as the minimum time to wait before retrying.
* Consider adding **backoff logic** (exponential or incremental) in your client.
* Keep in mind this rule is **global**—your request may be throttled even if your app isn’t sending traffic too quickly, because another client is creating accounts at the same time.