Request

Response

    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 TypeRate 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:

    HeaderDescription
    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:

    HeaderDescription
    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

    1. Monitor response headers - Track x-rate-limit-remaining to anticipate limits before hitting them.
    2. Implement exponential backoff - When receiving a 429 response, wait for the Retry-After duration, then retry with increasing delays if needed.
    3. Cache responses - Reduce API calls by caching profile data that doesn’t change frequently.
    4. Batch requests efficiently - Use GraphQL’s ability to request multiple fields in a single query to minimize API calls.