Rate limiting

This article explains the different types of rate limiting for the Mural API. We also cover what happens if your app sends too many requests.

How does Mural rate limiting work?

The Mural API, like many public APIs, is protected by rate limiting. This means that there is a maximum number of requests you can make in a given period, and if you exceed that maximum, further requests won’t succeed until the limit resets.

There are two dimensions to the limits enforced in the Mural API: by client application and by user. These two rate limits exist in parallel, and the request will be rejected if you exceed one of the limits.

A client application can exceed the user limit, but still make requests on behalf of other users.

Here's how the rate limits stack up:

• User rate limit: 25 requests/user/second
• Client application rate limit: 10,000/app/min

User rate limit

The default user rate limit is 25 requests/user/second.

This means that a single user, across all client applications that can act on their behalf, is limited to 25 requests in a one-second interval. This limit is per-user – it doesn’t change whether you have one user or one million.

Because this limit is per-user, it doesn’t help control traffic to Mural. If you have those one million users and they’re all making only 24 requests per second, they'd still be under the user rate limit. That’s why we also have a Client Application rate limit.

Client Application rate limit

The Client Application rate limit is 10,000 requests per 60 seconds.

This limit is a separate quota against all requests that a client app makes on any user’s behalf.

In our previous example of the client application with a million busy users, the API would reject most of those requests. New requests from this client app wouldn't be allowed until the beginning of the next 60-second period.

Response headers

Mural uses headers to communicate the current rate limit information to the API client making the request. Every request to the Mural API has two sets of these headers in its response.

For example, after a single request at the beginning of an interval, the per-user headers might look like this:

X-RateLimit-Limit: 25
X-RateLimit-Remaining: 24
X-RateLimit-Reset: 1627319309

The X-Ratelimit-Reset header is the UNIX timestamp for when the currently-measured interval ends.

The client application headers are the same, but starting with X-RateLimit-App-. For example, after one request:

X-RateLimit-App-Limit: 10000
X-RateLimit-App-Remaining: 9999
X-RateLimit-App-Reset: 1627319309

If you exceed these limits, either at the user limit or client application limit, the API call will be rejected with the HTTP error code 429 Too Many Requests until the interval ends. The response for blocked requests also has a JSON object as its body containing the same values as the headers described above.

If the client application limit is exceeded, the JSON body returned also has a type field with the client application ID.

For example:

{
   "limit": 10000,
   "remaining": 0,
   "reset": 1627319309,
   "type": "app:7b0316214e04-0a89-d284-1763-da46236c"
}