MusicBrainz API/Rate Limiting

From MusicBrainz Wiki


MusicBrainz has finite resources and wishes to make the MusicBrainz database available to as many the Internet community. However, at certain times of day the number of requests on XML_Web_Service exceed our capacity for handling these requests. If we attempted to honor each of these requests, we would overload all of our servers and that would degrade the service for everyone. For this reason we rate limit our Web Service, which limits the number of requests that clients can make in a given period of time.

When a request reaches our servers we check three conditions, in the following order:

  1. Source IP address: If a single IP address is making one request per second, the requests are all honored. If an IP address goes above 10 requests in 10 seconds, we instantly block that IP address and all requests from that IP address get a 503 error when making further requests. As soon as enough time passes such that the request rate for that IP drops below 10 in the last 10 seconds, requests are honored again.
  2. Global rate limit: If the total number of requests coming in to MusicBrainz exceeds our global rate limit in 10 seconds, all requests are rejected with a 503 error. This continues until the total count of requests in the last 10 seconds drops below the global rate limit. The current rate limit is set at 2,500 requests per 10 seconds. (equivalent to 250 requests per second)
  3. User-Agent string: Each application making requests to our web service must identify itself using the User-Agent string in the HTTP request header. If your application provides no User-Agent string, we will reject the request with a 403 Forbidden error. We have also blocked very common User-Agent strings from generic HTTP request libraries (see below for details). Some applications that use our own client libraries are making too many requests in certain times of the day, which has forced us to block these applications. Soon we're going to throttle some User-Agent string, rather than blocking them.

Current blocking rules

User-Agent String Version Action Allowed Rate
<blank> - blocked 0
Java any blocked 0
Python-urllib any blocked 0
Jakarta Commons-HttpClient any blocked 0
python-musicbrainz 0.7.3 blocked 0

(last update: 2011-12-19)

  • Explain why doing things at certain times of day are not smart
  • Explain our current blocking and give a schedule for when we move to throttling/blocking.
  • Mention that we can change the numbers at any time to protect the operation of the site.
  • Mention what a user/author can do about it and mention that our libs now support UA setting.