Rate Limits & Authentication
How to authenticate and stay within rate limits.
Authentication
All API endpoints (except /v1/auth/signup and health checks) require an API key passed in the Authorization header.
Get your API key
Using your key
Include the key in the Authorization header as a Bearer token:
curl https://api.maango.io/v1/domain/nytimes.com \ -H "Authorization: Bearer maango_sk_xxxxx"
Keep your key secret. Don't expose it in client-side code, public repos, or browser requests. Use it server-side only.
Rate Limits
Rate limits apply per API key across all endpoints.
| Window | Limit | Notes |
|---|---|---|
| Per minute | 200 | Resets every 60 seconds |
| Per day | 10,000 | Resets at midnight UTC |
| Per month | 100,000 | Resets on the 1st of each month |
| Signups | 3 / day | Per IP address, for /v1/auth/signup only |
Rate Limit Headers
Every API response includes rate limit headers so you can track your usage:
X-RateLimit-Limit-Minute: 200 X-RateLimit-Remaining-Minute: 195 X-RateLimit-Limit-Day: 10000 X-RateLimit-Remaining-Day: 9847
| Header | Description |
|---|---|
| X-RateLimit-Limit-Minute | Your per-minute limit |
| X-RateLimit-Remaining-Minute | Requests remaining in the current minute |
| X-RateLimit-Limit-Day | Your daily limit |
| X-RateLimit-Remaining-Day | Requests remaining today |
When you hit a limit
When you exceed a rate limit, you'll receive a 429 response with details about which limit was hit and when you can retry:
HTTP/1.1 429 Too Many Requests
Retry-After: 23
{
"error": "rate_limit_exceeded",
"message": "Rate limit exceeded. Try again in 23 seconds.",
"retry_after": 23,
"limit_type": "minute"
}The limit_type field tells you which limit was hit: minute, day, or month. Use the retry_after value (in seconds) to know when to retry.
Best Practices
Cache results
Domain policies don't change frequently. Cache results for domains you check often. A 24-hour TTL is reasonable for most use cases.
Use /batch for batch lookups
If you need to check multiple domains, use the /v1/batch endpoint instead of making individual calls. One request for up to 25 domains.
Check headers before retrying
Read the X-RateLimit-Remaining headers to avoid hitting limits. Back off proactively when remaining requests are low.
Handle 429s gracefully
Use the retry_after value from the response to implement exponential backoff. Don't hammer the API when rate limited.
Keep your key server-side
Never expose your API key in client-side code, browser requests, or public repositories. Proxy requests through your backend.