Inbound REST API rate limiting

  • Release version: Xanadu
  • Updated August 1, 2024
  • 2 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Inbound REST API rate limiting

    Inbound REST API rate limiting in ServiceNow allows you to control the volume of API requests processed per hour to prevent excessive load on your instance. You can create rules targeting all users, users with specific roles, or individual users, helping ensure fair and manageable API usage.

    Show full answer Show less

    Each node tracks request counts per user and updates the database every 30 seconds, so rate limits may take up to 30 seconds to take effect.

    Rate Limiting Priority and Behavior

    When multiple rate limit rules apply to a single API resource, ServiceNow applies them with the following priority:

    • Rules for a single user override rules for users with roles and all users.
    • Rules for users with specific roles override rules for all users.

    If a user has multiple roles subject to different limits, the strictest (lowest allowed requests) rule applies.

    For example, if user Abel Tuter has both an importadmin role (3 requests/hour) and an itil role (5 requests/hour), the 3 requests/hour limit applies.

    Response Headers and Error Handling

    When a request matches a rate limit rule, the response includes headers that provide rate limit details:

    • X-RateLimit-Limit: Number of requests allowed per hour.
    • X-RateLimit-Reset: Unix timestamp for when the quota resets.
    • X-RateLimit-Rule: Identifier of the enforced rate limit rule.

    If a request exceeds the limit, the response status is 429 Too Many Requests, and includes:

    • Retry-After header indicating seconds until the next allowed request.
    • An error JSON message specifying the rate limit exceeded.

    Managing Rate Limits

    • Create rate limit rules to specify request limits by user, role, or globally.
    • Reset rate limits to clear counts and violations for the current hour, useful during testing or troubleshooting.
    • Monitor counts and violations to evaluate if limits are appropriate and identify users exceeding limits.
    • Investigate violations to pinpoint which rules are being triggered and which users are impacted.

    Practical Benefits for ServiceNow Customers

    This capability helps ServiceNow customers protect their instances from abuse or accidental overload by controlling inbound API traffic effectively. It enables fine-grained control over API consumption by user or role, supports timely feedback to API clients via response headers, and provides tools to manage and analyze API usage patterns.

    To prevent excessive inbound REST API requests, set rules that limit the number of inbound REST API requests processed per hour. You can create rules to limit requests for specific users, users with specific roles, or all users.

    Note:
    As requests reach an instance, each node maintains a rate limit count per user. Every 30 seconds, the count is committed to the database. As a result, a rate limit rule may not take effect for up to 30 seconds.

    Rate limiting priority

    If an inbound REST API request matches multiple rate limit rules for the same resource, rate limiting priority is enforced as follows:
    • Rules set for Single user override rules for All users and rules for Users with role.
    • Rules set for Users with role override rules for All users.
    In this example, there are four rate limit rules for the same REST API resource: GET /now/v2/table/incident:
    Rate Limit Rules
    These rate limit rules are applied in the following order:
    1. Limit Incidents by User applies to ITIL User, who can submit up to 10 requests per hour.
    2. Limit Incidents by import admin Role applies to each user with the import_admin role. Each user with the import_admin role can submit up to three requests per hour.
    3. Limit Incidents by itil Role applies to each user with the itil role. Each user with the itil role can submit up to five requests per hour.
    4. Limit Incidents applies to all users. Each user can submit up to two requests per hour.

    When ITIL User makes the request GET /now/v2/table/incident, the request matches the criteria for three rules: Limit Incidents, Limit Incidents by itil Role, and Limit Incidents by User. Only the Limit Incidents by User rule is applied because it takes precedence over the other rules. As a result, ITIL User can submit a maximum of 10 requests per hour.

    If a user has two or more roles matching the criteria of multiple rate limiting rules for a REST API resource, the rule allowing the lowest number of requests applies to the user's requests for the resource. For the example rules in the figure above, assume that user Abel Tuter has both the import_admin role and the itil role. When Abel Tuter submits a request, it meets the criteria for both the Limit Incidents by admin Role rule and the Limit Incidents by itil Role rule. Only the Limit Incidents by admin Role rule is applied because it allows the lowest number of requests. As a result, Abel Tuter can submit a maximum of three requests per hour.

    REST API response headers

    You can generate inbound REST API requests using the Use the REST API Explorer or an HTTP client, such as Postman. If the request matches a rate limit rule, several HTTP response headers provide information about rate limiting:
    • X-RateLimit-Limit displays the number of requests allowed per hour.
    • X-RateLimit-Reset displays the Unix time until the next scheduled reset.
    • X-RateLimit-Rule displays the sys_id of the rate limit rule that is being enforced.

      Rate limit response headers

    If a request is denied because it exceeds the rate limit, the system returns a Retry After response header in addition to the response headers about rate limiting. The Retry After response header displays the number of seconds after which you can retry the request to avoid exceeding the rate limit. The following error response is returned:
    {
    "error": {
        "message": "Rate limit exceeded",
        "detail": "Rate limit of 10 requests per hour for Table API exceeded"
    },
    "status": "failure"
}

    The status of a denied request is 429 Too Many Requests.

    REST response status 429 Too Many Requests