> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stableyard.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limits

> The request limits on partner credentials, the headers that report them, and how to handle a 429.

Stableyard limits how many requests a caller can make in a time window. Responses report the quota that applies to them, so read the headers rather than hardcoding numbers.

## Rate limit headers

| Header | Sent on | Meaning |
| - | - | - |
| `RateLimit-Limit` | Responses from a deployment that enforces limits, including a `429` for an exceeded policy | Quota for the most constrained policy |
| `RateLimit-Remaining` | Same | Requests remaining in that policy's window |
| `RateLimit-Reset` | Same | Seconds until that window resets |
| `Retry-After` | Every `429` with code `rate_limited` | Seconds to wait before retrying |

A request counts against every policy that applies to it. On a success, the headers describe the most constrained of those policies; on a `429`, the policy that was exceeded. When a deployment does not enforce rate limits, responses carry no `RateLimit-*` headers.

## Default policies

These are the defaults for requests made with your app's credentials. Stableyard can configure them per deployment.

| Policy | Counts | Default | Window | `details.rule` |
| - | - | - | - | - |
| Reads per app environment | `GET`, `HEAD` and `OPTIONS` requests | 500 | 1 minute | `general_minute` |
| Writes per app environment | Every other method | 70 | 1 minute | `sensitive_minute` |
| Per app | Every request | 600 | 1 minute | `partner_app_minute` |
| Read burst per app | `GET`, `HEAD` and `OPTIONS` requests | 120 | 10 seconds | `partner_app_burst` |
| Payments per app | `POST` to `/v2/payments` and its sub-paths | 180 | 1 minute | `payments_app_minute` |
| Deposit addresses per app | `POST` to `deposit-addresses` paths, including `/check` | 120 | 1 minute | `deposit_address_app_minute` |
| Per IP address | Every request from one IP address | 500 | 1 minute | None. `details.reason` is `rate_limit_exceeded` |

A `POST /v2/payments`, for example, counts against writes per app environment, per app, and payments per app.

## Handle a 429

```json theme={null}
{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests",
    "details": {
      "rule": "payments_app_minute",
      "limit": 180,
      "remaining": 0,
      "resetAt": "2026-10-01T12:01:00Z",
      "retryAfterSeconds": 23
    }
  }
}
```

1. **Wait for `Retry-After`** before sending the request again.
2. **Reuse the same `Idempotency-Key`** when you retry a write. See [Retrying safely](/errors#retrying-safely).
3. **Spread the load.** React to [webhooks](/webhooks) instead of polling every resource, and page through lists with their cursors.

| `details.reason` | Meaning |
| - | - |
| Absent, with `details.rule` | A policy in the table above was exceeded |
| `rate_limit_exceeded` | The per-IP limit was exceeded |
| `rate_limiter_unavailable` | Stableyard could not check the limit and refused the request rather than let it through. Retry shortly |
| `abuse_blocked` | The IP address is temporarily blocked. By default, more than 20 requests to routes that do not exist within 10 minutes block it for an hour. `Retry-After` says how long |

Not every `429` is a rate limit. `payment_option_limit_reached` means too many options were created for one payment. See [Errors](/errors#payments).

## Related

<CardGroup cols={2}>
  <Card title="Errors" icon="triangle-exclamation" href="/errors">
    Every error code and which ones to retry.
  </Card>

  <Card title="Idempotency" icon="key" href="/idempotency">
    Retry a write without doing it twice.
  </Card>

  <Card title="Webhooks" icon="bolt" href="/webhooks">
    Learn about changes without polling.
  </Card>

  <Card title="Environments" icon="server" href="/environments">
    Base URLs and what is isolated between environments.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.