Rate Limits
Request limits per endpoint category, response headers, and how to back off gracefully.
How rate limiting works
EPD enforces rate limits per API key, per minute. Limits are tiered by endpoint category — write operations that move money have a lower limit than read operations to protect against runaway automation.
Every response includes headers showing exactly how much of your budget remains.
Limits by category
| Category | Limit | Applies to |
|---|---|---|
payment | 10 req / min | Create order, refund order, create subscription, add / remove payment method |
data | 60 req / min | All read and write operations on customers, products, plans, transactions, subscriptions (non-billing), account |
webhook | 10 req / min | All webhook endpoint operations — create, update, delete, rotate secret, test, replay |
Limits are per API key. If a high-volume reporting service and your billing worker share one key, their requests compete against the same bucket. Give each service its own restricted key.
Response headers
Every API response includes these headers so you can track your budget without waiting for a 429:
| Header | Type | Description |
|---|---|---|
X-RateLimit-Limit | integer | Total requests allowed in the current window |
X-RateLimit-Remaining | integer | Requests remaining before the limit is hit |
X-RateLimit-Reset | Unix timestamp | When the current window resets (seconds since epoch) |
Retry-After | integer | Only on 429. Seconds to wait before retrying |
When you hit the limit
EPD returns 429 Too Many Requests with a JSON error body:
{
"error": {
"type": "rate_limit_error",
"code": "rate_limit_exceeded",
"message": "Too many requests. Retry after 4 seconds.",
"request_id": "req_01hx..."
}
}
Backing off correctly
The Retry-After header tells you exactly how many seconds to wait. Honor it — retrying sooner just extends the lockout.
If multiple workers all retry at exactly Retry-After, they spike together. Add ±20–30% random jitter to spread the load.
After 3–5 retries, surface the error to the operator. Persistent rate-limit errors usually mean a runaway loop, not a transient blip.
Sandbox limits
Sandbox keys are subject to the same limits as live keys. Test your backoff and retry logic in sandbox before going live — it is the only way to verify it works under real conditions.
MCP server
The MCP server uses the same rate limit categories as the REST API. See Rate limits in MCP for agent-specific guidance on staying under the limit.