Rate limits

Rate limiting keeps the Escrow API stable. There is a limited number of requests you can make per time window for each endpoint family. Going beyond that limit returns HTTP 429 with error.code RATE_LIMITED. Limits apply per merchant, with a separate quota for test and live (your sk_test_ / sk_live_ key). Hitting the limit on one family does not freeze other families.

Rate limit headers

On success and on 429, read these response headers:

Header	Meaning
`x-ratelimit-limit`	Max requests permitted in the current window for this family.
`x-ratelimit-remaining`	Requests left in the current window.
`x-ratelimit-reset`	Seconds until the current window ends, when you can retry.

On 429 you also get Retry-After (seconds), matching x-ratelimit-reset.

Error body

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "details": {
      "nextStep": "Wait 42 seconds and try again",
      "resetInSeconds": 42,
      "limit": 100,
      "family": "standard",
      "endpoint": "Standard secret key routes"
    }
  },
  "meta": {
    "requestId": "req_01hxyz"
  }
}

Standard limits

Most secret key routes share the standard family.

Mode	Limit
Test (`sk_test_`)	100 requests per 60 seconds
Live (`sk_live_`)	300 requests per 60 seconds

Test mode is for development and integration testing, not load testing.

Extended limits

These foundational routes have their own higher buckets in live mode so critical flows keep moving. In test mode they use the standard limit above.

Endpoint family	Live limit (per 60 seconds)
`GET /identity/banks`	600
`POST /identity/bank-accounts/verify`	300
`POST /checkout/sessions`	200
Escrow writes (`POST /escrows`, release, refund, cancel, disputes, resolve)	200
`POST /withdrawals`	150

Handling a 429

Read x-ratelimit-reset (seconds).
Pause requests to that endpoint family until the window ends.
If you see sustained 429s across many families, pause and investigate. An unchecked poll loop is usually the cause.

Staying within limits

Prefer webhooks over polling GET /escrows/{id} after checkout or payout.
Cache stable lookups such as GET /identity/banks.
Page through lists (default 20, max 100). See Pagination.
Use idempotency keys on money moving POSTs so timeouts do not double release or double pay.

If you need higher sustained limits for production traffic, contact Demat support with the endpoint family, expected peak rate, and a short description of your integration.

Get started

API basics

Integrations

Rate limit headers

Error body

Standard limits

Extended limits

Handling a 429

Staying within limits

​Rate limit headers

​Error body

​Standard limits

​Extended limits

​Handling a 429

​Staying within limits

Rate limit headers

Error body

Standard limits

Extended limits

Handling a 429

Staying within limits