REST API Rate Limits

Rate limits on PagerDuty's REST API help ensure that our resources are available for users and their apps when they need them, and also protect against fraudulent activity.

In order to make the best use of REST API rate limits and minimize disruptions to your applications, we recommend the following:

  • Make use of rate limit headers: You can update your application to parse the ratelimit-remaining and ratelimit-reset response headers. If your application is being rate limited, the ratelimit-reset header will let you know how many seconds to wait before retrying.
  • Use one "bot user" per application deployment: If you use PagerDuty user API keys as bot users for applications, create a separate bot user for each application deployment (e.g., "Acme Production Bot User", "Acme Test Bot User", etc.). With this approach, rate limits for each application deployment will be kept separate.

Troubleshooting

If you experience throttling due to our API rate limit, we recommend trying the following steps in the order presented :

  1. If you're using user API keys, we recommend adding more users and spreading out the REST API request load.
  2. For customers in the US service region:
    1. If you have a bot user, we recommend registering one scoped OAuth app per environment (e.g., "staging," "production," etc.) and using the appropriate app token to access the REST API. Please read our developer documentation Register an App for more information. This approach is especially advantageous, since global API keys may be deprecated in the future for security's sake.
    2. You can also register a private scoped OAuth app in addition to using a user token. The user will first go through the user login and consent screen, and will then be able to access the REST API. This will effectively double your API rate limit, since you can use the token associated with the registered app, as well as with the user.

🚧

Service Region Restriction

App Registration is only available in the US service region. There are plans to expand this feature to the EU region in 2024.

FAQ

Will rate limits affect my application?

Expand

In most cases, your application should experience similar or more generous rate limits than it does today. However, rate limiting can be complicated and there may be some exceptions depending on how your application uses the REST API.

If you have never experienced rate limiting or your code already gracefully responds to 429 HTTP response codes, you are likely already prepared.

How can I prepare for rate limits?

Expand

We have introduced new rate limiting headers on HTTP responses from our REST API. These headers are identical to the ones that will be present when the new rate limiting system is fully rolled out. For a period of time, you will not receive a 429 response when the limit is reached, which gives you some time to adjust your application and make any required updates.

If your application is mission critical or does not handle rate limiting, you can incorporate these headers into your applications to minimize any potential disruptions.

Please see REST API Rate Limits in our developer documentation for more information.

When do rate limits go into effect?

Expand

Your applications can consume the new rate limiting headers that are currently active as of October/November 2023. You can expect to see 429 responses when limits are reached over the initial weeks of the feature rollout.

Please see Rate Limiting in our developers documentation for more information.