Getting Started
Rate Limits & Quotas
Understand rate limits, throttling behaviors, and response headers across the 1st Services API.
Rate Limits & Quotas
To ensure high availability and prevent abuse, all endpoints in the 1st Services API enforce rate limits based on your account tier and API key scopes.
Rate Limit Headers
Every HTTP response from api.1st-services.com includes standard rate limit headers:
| Header | Description |
|---|---|
X-RateLimit-Limit | The maximum number of allowed requests in the current 60-second window. |
X-RateLimit-Remaining | The remaining number of requests available before hitting the rate limit. |
X-RateLimit-Reset | Unix epoch timestamp (in seconds) when the current rate limit window resets. |
Example Response Headers
HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 1200
X-RateLimit-Remaining: 1184
X-RateLimit-Reset: 1771849200
Tier Rate Limits
| Tier | General API Limits | Temp Mail API | URL Shortener API |
|---|---|---|---|
| Free Developer | 60 req / min | 120 req / min | 300 req / min |
| Pro Plan | 1,200 req / min | 3,000 req / min | 10,000 req / min |
| Enterprise | Custom (10,000+ req/min) | Custom | Custom (Dedicated Anycast) |
Handling 429 Too Many Requests
If you exceed the rate limit, the API returns an HTTP 429 status code with a JSON payload and a Retry-After header:
HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json
{
"status": "error",
"code": "RATE_LIMIT_EXCEEDED",
"message": "You have exceeded your request quota. Please wait before retrying.",
"retry_after_seconds": 12
}
Implementing Exponential Backoff
When writing automated integrations, implement exponential backoff with jitter:
TypeScript
async function fetchWithRetry(url: string, options: RequestInit, retries = 3): Promise<Response> {
try {
const res = await fetch(url, options)
if (res.status === 429 && retries > 0) {
const retryAfter = parseInt(res.headers.get('Retry-After') || '2', 10)
const jitter = Math.random() * 500
await new Promise(resolve => setTimeout(resolve, retryAfter * 1000 + jitter))
return fetchWithRetry(url, options, retries - 1)
}
return res
} catch (err) {
if (retries > 0) {
await new Promise(resolve => setTimeout(resolve, 1000))
return fetchWithRetry(url, options, retries - 1)
}
throw err
}
}