Rate Limits
Rate limits control how frequently you can call an API. They help maintain consistent service quality and availability for all users.
Default Limits
The User Profile API enforces the following rate limits:
| Token Type | Rate Limit |
|---|---|
| three-legged access token (Authorization Code) | 500 requests per minute |
These limits are generous and should not impact typical usage. However, applications generating unusually high call volumes may be affected.
Response Headers
Every successful response includes rate limit information in the headers:
| Header | Description |
|---|---|
| x-rate-limit-limit | Maximum requests allowed in the current window |
| x-rate-limit-remaining | Requests remaining in the current window |
| x-rate-limit-used | Requests made in the current window |
| x-rate-limit-reset | UTC timestamp when the rate limit resets |
| x-ads-rate-limit-type | Type of rate limit applied (2lo or 3lo) |
| x-ads-rate-limit-value | Identifier for the rate-limited entity |
User-Level Rate Limits
When user-level rate limits apply, additional headers are included:
| Header | Description |
|---|---|
| x-rate-limit-user-limit | Maximum user requests allowed in the current window |
| x-rate-limit-user-remaining | User requests remaining in the current window |
| x-rate-limit-user-used | User requests made in the current window |
| x-rate-limit-user-reset | UTC timestamp when the user rate limit resets |
| x-ads-rate-limit-user-value | User ID being rate-limited |
Handling Rate Limit Errors
When your application exceeds the rate limit, the API returns HTTP 429 “Too Many Requests”. The response includes a Retry-After header indicating how many seconds to wait before retrying.
Example Response:
HTTP/1.1 429 Too Many Requests
Content-Type: application/json; charset=utf-8
Retry-After: 25
{
"error": {
"code": 429,
"message": "Too Many Requests"
}
}
Show More
Best Practices
- Monitor response headers - Track
x-rate-limit-remainingto anticipate limits before hitting them. - Implement exponential backoff - When receiving a 429 response, wait for the
Retry-Afterduration, then retry with increasing delays if needed. - Cache responses - Reduce API calls by caching profile data that doesn’t change frequently.
- Batch requests efficiently - Use GraphQL’s ability to request multiple fields in a single query to minimize API calls.