---
sourceDocument: Yokohama API Reference
sourceDocumentLink: https://www.servicenow.com/docs/r/yokohama/api-reference

 Release :

    - yokohama

ft:locale :

    - en-US

ft:publication_title :

    - Yokohama API Reference

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# Inbound REST API rate limiting

# Inbound REST API rate limiting {#ariaid-title1}

* Release version: Yokohama
* 
* Updated January 30, 2025
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 2 minutes to read

Summarize  
![AI sparkle icon](https://servicenow.com/docs/portal-asset/ai-sparkle-icon) 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 Yokohama release helps prevent excessive API requests by setting rules that limit the number of requests processed per hour.
These rules can target specific users, users with certain roles, or all users to control API usage efficiently and avoid performance degradation.
Show full answer Show less  
Each node on an instance tracks rate limit counts per user and commits updates to the database every 30 seconds, which means new rate limit rules may take up to 30 seconds to fully apply.

## Rate Limiting Priority

When multiple rate limit rules apply to the same API resource, the system enforces priority as follows:

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

For users with multiple roles matching different rules, the strictest rule (lowest allowed requests) is applied.

## REST API Response Headers

When a request is rate limited, response headers provide details:

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

If a request exceeds the limit, the response includes a **Retry-After** header indicating when the client can retry, and returns HTTP status **429 Too Many Requests** with an error message indicating the limit was exceeded.

## Managing Rate Limits

* **Create:** Define rate limit rules to control inbound API request volumes per hour.
* **Reset:** Reset rate limit counters and clear violations for a rule to restore request allowance immediately.
* **Monitor:** Track rate limit counts and violations to ensure rules are appropriately set and not overly restrictive.
* **Investigate:** Identify which users and rules are causing violations to adjust limits or address excessive usage.

This functionality enables ServiceNow customers to effectively manage API consumption, protect system performance, and maintain service availability by enforcing fair and transparent request limits.  
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 {#inbound-REST-API-rate-limiting__section_isk_1gr_hdb}

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.
{#inbound-REST-API-rate-limiting__ul_oy2_xrk_hdb}  
In this example, there are four rate limit rules for the same REST API resource: `GET /now/v2/table/incident`:  
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.
{#inbound-REST-API-rate-limiting__ul_k4q_qjr_hdb}

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 {#inbound-REST-API-rate-limiting__section_l5l_5my_hdb}

You can generate inbound REST API requests using the [Use the REST API Explorer](https://www.servicenow.com/docs/VV5d3pcHRv4pFxM~yEJQZA "In this tutorial you will use the REST API Explorer to test the ServiceNow REST APIs.") 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.

{#inbound-REST-API-rate-limiting__ul_xpr_w4y_hdb}  
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.

* **[Create an inbound REST API rate limit](https://www.servicenow.com/docs/vd2BQdewqvUXw1f0J3uunQ)**   
  Create rate limit rules to limit the number of inbound REST API requests processed per hour.
* **[Reset an inbound REST API rate limit](https://www.servicenow.com/docs/M9kUGKk4UVnE1AMAQteDHQ)**   
  Reset a rate limit rule to reset the rate limit count to zero (0) and delete any violations for the current hour.
* **[Monitor inbound REST API rate limit counts and violations](https://www.servicenow.com/docs/XLbImFKOilPUZM2CYISI_A)**   
  To determine if you have set a rate limit rule appropriately, monitor the counts and violations for inbound REST API requests that are restricted by the rule.
* **[Investigate inbound REST API rate limit violations](https://www.servicenow.com/docs/9Myi8iB6X4oY1D9Rv606uA)**   
  Investigate rate limit violations to determine which rate limit rules are being exceeded and which users are exceeding those rate limits.