API Rate Limits
To ensure platform stability and prevent abuse, Headless Domains enforces rate limits on certain API endpoints.
Current Rate Limits in Production
| Endpoint | Limit | Bucket key | Env var to override |
|---|---|---|---|
/api/v1/agents/provision |
10 per minute | per IP | RATELIMIT_PROVISION_AGENT |
/api/v1/lookup/<domain> |
60 per minute | per IP | RATELIMIT_LOOKUP |
/lookup (alias) |
60 per minute | per IP | same as above |
/search |
60 per minute | per IP | RATELIMIT_SEARCH |
/api/v1/integrations/shakeshift/slds |
30 per minute | per IP | RATELIMIT_SHAKESHIFT |
/api/health |
exempt (no limit) | - | - |
| Everything else | unlimited | - | - |
Are these limits reasonable?
Yes, these are highly sensible production rate limits! Here is why:
- Agent Provisioning (10/min): Creating a new identity is a one-time setup action. 10 per minute per IP is more than enough for legitimate use and effectively stops botnets from flooding the database with spam accounts.
- Lookups & Search (60/min): 1 request per second per IP is generous for individual users or agents checking availability. It successfully prevents aggressive scrapers from harvesting your entire namespace.
- Shakeshift Sync (30/min): Partner integrations typically sync every few minutes, so 30 per minute provides plenty of headroom while protecting backend database performance.