Rate Limits
The VaultPAM API enforces per-client rate limits to protect service stability. All API responses include x-ratelimit-* headers so your client can track its current consumption and back off gracefully before hitting a limit.
Response Headers
Every API response includes the following headers:
| Header | Type | Description |
|---|---|---|
x-ratelimit-limit | integer | Maximum requests allowed in the current window |
x-ratelimit-remaining | integer | Requests remaining in the current window |
x-ratelimit-reset | Unix timestamp (seconds) | When the current window resets |
On a 429 Too Many Requests response, an additional header is included:
| Header | Type | Description |
|---|---|---|
retry-after | integer (seconds) | Minimum time to wait before retrying |
All headers use lowercase names.
Rate Limit Categories
The API applies different limits depending on the operation type and calling context. The x-ratelimit-* headers in each response reflect the limit category applicable to that specific request.
Reference values (guidance only — treat x-ratelimit-* headers as authoritative):
| Category | Limit |
|---|---|
| Login attempts per IP | 60 per minute |
| API requests per IP | 300 per minute |
| API requests per authenticated user | 120 per minute |
| Sensitive operations per user | 30 per minute |
The limits shown above document the current defaults. Use the x-ratelimit-limit and x-ratelimit-remaining values in each response to make retry decisions — the published numbers are subject to change without notice.
Handling 429 Responses
When you receive a 429 Too Many Requests response:
- Read the
retry-afterheader value (seconds). - Pause your request loop for at least that duration.
- Retry the request.
Example response:
HTTP/1.1 429 Too Many Requests
x-ratelimit-limit: 120
x-ratelimit-remaining: 0
x-ratelimit-reset: 1747483200
retry-after: 37
Content-Type: application/json
{
"error": "RATE_LIMITED",
"message": "Too many requests. Retry after 37 seconds."
}
Recommended Client Patterns
Check remaining budget before bulk operations
Read x-ratelimit-remaining after each response. If it drops below a threshold (for example, 10), introduce a pause before the next request to avoid triggering a 429.
Exponential backoff for transient 429s
If retry-after is not present or you receive multiple consecutive 429 responses, use exponential backoff with jitter:
wait = min(base * 2^attempt + random_jitter, max_wait)
Log x-ratelimit-reset for debugging
When diagnosing rate-limit issues, log the x-ratelimit-reset Unix timestamp alongside the response. Convert to a human-readable time to understand when the window rolls over.
Next Steps
- Authentication Flow — acquire tokens before making API calls
- curl Quickstart — see rate-limit headers in action