Rate Limiting
Understanding and handling rate limits in the Fayda Authentication API.
Overview
To ensure fair usage and system stability, the Fayda Authentication API implements rate limiting. When a rate limit is exceeded, the API will return a
429 Too Many Requests error.Rate Limit Types
Limits are applied based on your API key's plan and on a per-FCN basis to prevent abuse.
API Key Rate Limits
These limits apply to the total number of requests made with a specific API key.
| Plan | Limit | Window |
|---|---|---|
| Free | 100 requests | Per hour |
| Standard | 1,000 requests | Per hour |
| Professional | 5,000 requests | Per hour |
| Enterprise | Custom | Custom |
FCN-Specific Rate Limits
To prevent abuse against a single user, additional limits are applied to OTP initiation requests for each FCN.
| Endpoint | Limit | Window |
|---|---|---|
| /api/fayda/otp/initiate | 5 requests | Per 15 minutes |
Rate Limit Headers
The API provides the following headers in the response to help you track your current rate limit status.
| Header | Description |
|---|---|
| X-RateLimit-Limit | The maximum number of requests allowed in the current time window. |
| X-RateLimit-Remaining | The number of requests remaining in the current window. |
| X-RateLimit-Reset | The time at which the current window resets, in UTC epoch seconds. |
| Retry-After | The number of seconds to wait before making a new request. This header is only sent when you have been rate-limited. |
Handling Rate Limits
When you are rate-limited, the API returns an error response.
Error Response (429 Too Many Requests)
json
{
"success": false,
"error": "RATE_LIMIT_EXCEEDED",
"message": "You have exceeded the number of allowed requests.",
"statusCode": 429,
"details": {
"retryAfter": 60
},
"timestamp": "2023-07-20T12:34:56.789Z"
}Best Practices for Handling Rate Limits
- Implement exponential backoff: When you receive a 429 error, wait for the duration specified in the
Retry-Afterheader before retrying. If the header is not present, use an exponential backoff strategy (e.g., wait 1s, then 2s, then 4s). - Cache responses: Avoid making redundant API calls by caching responses where appropriate.
- Monitor headers: Proactively monitor the
X-RateLimit-Remainingheader to slow down requests as you approach the limit. - Upgrade your plan: If you consistently hit rate limits, consider upgrading to a higher plan for increased capacity.