Rate Limits
All endpoints are rate-limited per API key (authenticated) or per IP (public endpoints).
Endpoint Limits
| Endpoint | Method | Limit | Window | Auth Required |
|---|---|---|---|---|
/magen-verify-start | POST | 100/min | 60s | No |
/magen-verify-check | POST | 200/min | 60s | No |
/magen-verify-session/:id | GET | 300/min | 60s | Yes |
/magen-session-delete/:id | DELETE | 50/min | 60s | Yes |
/magen-session-token | POST | 100/min | 60s | Yes |
/record-honeypot-session | POST | 500/min | 60s | No |
Rate Limit Headers
Every response includes these headers to help you monitor your usage:
X-RateLimit-LimitMaximum requests allowed in windowX-RateLimit-RemainingRequests remaining in current windowX-RateLimit-ResetSeconds until window resets429 Too Many Requests
When you exceed the rate limit, the API returns a 429 status with details about when you can retry:
{
"success": false,
"error": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded",
"retry_after": 23,
"request_id": "req_abc123"
}Exponential Backoff Example
Implement exponential backoff to gracefully handle rate limits:
1async function fetchWithBackoff(url: string, options: RequestInit, maxRetries = 3) {
2 let retries = 0;
3
4 while (retries < maxRetries) {
5 const response = await fetch(url, options);
6
7 if (response.status === 429) {
8 const retryAfter = parseInt(response.headers.get('Retry-After') || '1');
9 const backoffTime = Math.min(retryAfter * 1000, Math.pow(2, retries) * 1000);
10
11 console.log(`Rate limited. Retrying in ${backoffTime}ms...`);
12 await new Promise(resolve => setTimeout(resolve, backoffTime));
13 retries++;
14 continue;
15 }
16
17 return response;
18 }
19
20 throw new Error('Max retries exceeded');
21}Best Practices
1
Cache session tokens
Reuse tokens within their TTL instead of generating new ones for each request.
2
Implement backoff
Use exponential backoff on 429 responses to avoid hammering the API.
3
Batch signals
Collect entropy signals client-side and send once per verification instead of streaming.
4
Monitor usage
Track X-RateLimit-Remaining header to proactively avoid hitting limits.