Rate limits

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

{
  "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
    }
  }
}

Wait for Retry-After before sending the request again.
Reuse the same Idempotency-Key when you retry a write. See Retrying safely.
Spread the load. React to 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

Every error code and which ones to retry.

Idempotency

Retry a write without doing it twice.

Webhooks

Learn about changes without polling.

Environments

Base URLs and what is isolated between environments.

Concepts

Onboarding

Money movement

Automation

Webhooks

Reference data

Rate limit headers

Default policies

Handle a 429

Errors

Idempotency

Webhooks

Environments

​Rate limit headers

​Default policies

​Handle a 429

​Related

Errors

Idempotency

Webhooks

Environments

Rate limit headers

Default policies

Handle a 429

Related