Skip to content

The Open Source DocuSign Alternative.

docs(api): document rate limit headers and 429 variants (#3133)

Ephraim Duncan05f646b326c5
diff --git a/apps/docs/content/docs/developers/api/rate-limits.mdx b/apps/docs/content/docs/developers/api/rate-limits.mdx
index 95b0a68fe..878db97b6 100644
--- a/apps/docs/content/docs/developers/api/rate-limits.mdx
+++ b/apps/docs/content/docs/developers/api/rate-limits.mdx
@@ -11,6 +11,12 @@ Documenso enforces rate limits on all API endpoints to ensure service stability.
## HTTP Rate Limits
+The rate limit applies to:
+
+- `/api/v1/*`
+- `/api/v2/*`
+- `/api/v2-beta/*`
+
**Limit:** 1000 requests per minute per IP address
**Response:** 429 Too Many Requests
@@ -19,7 +25,7 @@ Documenso enforces rate limits on all API endpoints to ensure service stability.
this value, in which case you can be rate-limited before reaching the global limit.
</Callout>
-### Rate Limit Response
+### Global per-IP 429 Response
```json
{
@@ -27,10 +33,22 @@ Documenso enforces rate limits on all API endpoints to ensure service stability.
}
```
-<Callout type="warn">
- No rate limit headers are currently provided. When you receive a 429 response, wait at least 60
- seconds before retrying.
-</Callout>
+### Rate Limit Headers
+
+Responses from `/api/v1/*`, `/api/v2/*`, and `/api/v2-beta/*` include these headers. The only
+exception is CORS preflight (`OPTIONS`) requests, which are answered before the rate limiter runs
+and carry no rate limit headers:
+
+| Header | Description |
+| ----------------------- | ---------------------------------------------------------------------- |
+| `X-RateLimit-Limit` | Maximum requests allowed in the current global window |
+| `X-RateLimit-Remaining` | Requests remaining in the current global window |
+| `X-RateLimit-Reset` | End of the current global window, as a Unix epoch timestamp in seconds |
+
+A 429 response from a windowed limiter also includes `Retry-After`, in seconds, with a minimum
+value of `1`. The global API limit uses fixed, epoch-aligned one-minute buckets, so the actual wait
+until the next window is between 1 and 60 seconds. Honor `Retry-After` exactly instead of sleeping
+for a fixed 60 seconds. See the [Retry-After handling example](/docs/developers/examples/common-workflows#error-handling-patterns).
## Resource Limits
@@ -44,24 +62,55 @@ Beyond HTTP rate limits, your account has usage limits based on your subscriptio
| Total Recipients | 10 | Unlimited | Unlimited | Unlimited |
| Direct Templates | 3 | Unlimited | Unlimited | Unlimited |
-### Error Response
+### Organisation Limit 429 Responses
+
+Organisation windowed limits and organisation monthly quotas produce 429 responses whose body
+shape depends on the API version, and neither matches the global per-IP limiter's
+`{ "error": "..." }` body.
+
+On `/api/v1/*`, the body contains only a message:
-When you exceed a resource limit:
+```json
+{
+ "message": "Too many requests, please try again later. Contact support if you require higher limits."
+}
+```
+
+On `/api/v2/*` and `/api/v2-beta/*`, the body is a structured error object:
```json
{
- "error": "You have reached your document limit for this month. Please upgrade your plan.",
- "code": "LIMIT_EXCEEDED",
- "statusCode": 400
+ "message": "Too many requests, please try again later. Contact support if you require higher limits.",
+ "code": "TOO_MANY_REQUESTS",
+ "data": {
+ "code": "TOO_MANY_REQUESTS",
+ "httpStatus": 429,
+ "appError": {
+ "code": "TOO_MANY_REQUESTS",
+ "message": "Too many requests, please try again later. Contact support if you require higher limits."
+ }
+ }
}
```
+Organisation windowed limit responses include the `X-RateLimit-*` headers and `Retry-After` for
+their own window. Monthly quota responses carry no quota-specific rate limit headers or
+`Retry-After` because the quota is not a time window; rely on the status code and message instead.
+
## Error Codes
-| Code | Status | Description |
-| ------------------- | ------ | ----------------------------- |
-| `TOO_MANY_REQUESTS` | 429 | HTTP rate limit exceeded |
-| `LIMIT_EXCEEDED` | 400 | Resource usage limit exceeded |
+| Code | Status | Description |
+| ------------------- | ------ | ------------------------------------------------------------------ |
+| `TOO_MANY_REQUESTS` | 429 | Global per-IP, organisation windowed, or monthly quota exceeded |
+| `LIMIT_EXCEEDED` | 400 | Resource usage limit exceeded |
+
+There are three sources of `TOO_MANY_REQUESTS` responses:
+
+1. The global per-IP limit, returning the `{ "error": "..." }` body shown above.
+2. Organisation windowed rate limits for the `api`, `document`, and `email` counters.
+3. Organisation monthly quotas for the same three counters. Every authenticated API request
+ consumes the `api` counter, so any endpoint can return this 429 once the monthly API quota is
+ exhausted — not just envelope-related ones.
---
diff --git a/apps/docs/content/docs/developers/examples/common-workflows.mdx b/apps/docs/content/docs/developers/examples/common-workflows.mdx
index 704bf415f..5bdf32cdf 100644
--- a/apps/docs/content/docs/developers/examples/common-workflows.mdx
+++ b/apps/docs/content/docs/developers/examples/common-workflows.mdx
@@ -1000,9 +1000,12 @@ async function fetchWithRetry(
// Retry on rate limit
if (response.status === 429) {
const retryAfter = response.headers.get('Retry-After');
- const delay = retryAfter ? parseInt(retryAfter) * 1000 : baseDelayMs * Math.pow(2, attempt);
+ // Honor Retry-After exactly; the cap only applies to the exponential fallback.
+ const delay = retryAfter
+ ? parseInt(retryAfter) * 1000
+ : Math.min(baseDelayMs * Math.pow(2, attempt), maxDelayMs);
console.log(`Rate limited, waiting ${delay}ms...`);
- await new Promise((resolve) => setTimeout(resolve, Math.min(delay, maxDelayMs)));
+ await new Promise((resolve) => setTimeout(resolve, delay));
continue;
}