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 |
|---|---|---|---|
/agent/auth, /agent-auth, /api/v1/agents/provision |
10 per hour | 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/v1/integrations/shakeshift/pricing |
30 per minute | per IP | RATELIMIT_SHAKESHIFT |
/api/health |
exempt (no limit) | - | - |
| Everything else | unlimited | - | - |
All anonymous provisioning aliases share one quota; switching URLs does not
start a new bucket. Client addresses come from request.remote_addr unless the
immediate peer belongs to the reviewed private/shared-address or Cloudflare proxy
networks. Trusted X-Forwarded-For chains are evaluated right-to-left, and
CF-Connecting-IP is never trusted directly. Deployments may replace the
reviewed defaults with RATELIMIT_TRUSTED_PROXY_CIDRS, a comma-separated CIDR
list, when their proxy topology changes.
Are these limits reasonable?
Yes, these are highly sensible production rate limits! Here is why:
- Agent Provisioning (10/hour): Creating a new identity is a one-time setup action. The shared per-IP limit covers the canonical route and both compatibility aliases.
- 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.