Entity-level rate limits (resource protection)
These limits exist to prevent repeated concurrent mutations on the same entity, which can cause:- Parallel processing contention
- Unnecessary retries
- Backend instability
- Incident-level load amplification
Entity types
Entity-level rate limits are enforced for the following entities:- Customer
- Subscription
- Customer resource (customer and resource combination)
- Customer-based operations →
customerId - Subscription-based operations →
subscriptionId - Customer and resource operations →
customerId:resourceId
Example
If the entity-level limit is 30 calls per minute:- Calling
cancelSubscription30 times per minute for the same subscription ID is allowed - The 31st call for that subscription will fail
- Calls for other subscriptions are unaffected
- Calls for other customers are unaffected
- The calls target different endpoints
- The calls use different HTTP methods
Subscription endpoints
| Route | Rate-limited entity (key) | Rate limit (calls per minute per entity) |
|---|---|---|
POST /subscriptions | customerId:resourceId or customerId | 30 |
POST /subscriptions/:id/transfer | subscriptionId | 30 |
POST /subscriptions/:id/migrate | subscriptionId | 30 |
POST /subscriptions/:id/delegate | subscriptionId | 30 |
DELETE /subscriptions/:id/future-update/pending-payment | subscriptionId | 30 |
DELETE /subscriptions/:id/future-update/schedule | subscriptionId | 30 |
PATCH /subscriptions/:id | subscriptionId | 30 |
POST /subscriptions/:id/cancel | subscriptionId | 30 |
Customer endpoints
| Route | Rate-limited entity (key) | Rate limit (calls per minute per entity) |
|---|---|---|
PATCH /customers/:id | customerId | 30 |
POST /customers/:id/archive | customerId | 30 |
POST /customers/:id/unarchive | customerId | 30 |
POST /customers/:id/payment-method | customerId | 30 |
DELETE /customers/:id/payment-method | customerId | 30 |