Buttondown logo

Rate limits in the API

Buttondown enforces two types of rate limits:

EndpointRate limit
All API endpoints600 requests per minute
POST /v1/subscribers100 requests per day

If you find yourself running into the limit of 100 subscribers a day, it's likely due to one of two things:

  1. You are onboarding and performing an import one subscriber at a time. We'd encourage you to use the import path instead to upload multiple subscribers in bulk.
  2. You have a particularly high-volume list that is growing rapidly.

Rate limit headers

Buttondown returns rate limit information in the response headers on every API request:

HeaderDescription
X-RateLimit-LimitThe maximum number of requests allowed in the current window
X-RateLimit-RemainingThe number of requests remaining in the current window
X-RateLimit-ResetUnix timestamp (in seconds) when the rate limit window resets

Here's an example of the headers you might see:

import requests

url = "https://api.buttondown.com/v1/subscribers"
headers = {
  "Authorization": "Token $BUTTONDOWN_API_KEY"
}

response = requests.request("GET", url, headers=headers)
print(response.text)
Response
HTTP/1.1 200 OK
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 595
X-RateLimit-Reset: 1735776060

Exceeding the rate limit

If you exceed the rate limit, the API will return a 429 status code with a Retry-After header indicating how many seconds to wait before retrying:

import requests

url = "https://api.buttondown.com/v1/subscribers"
headers = {
  "Authorization": "Token $BUTTONDOWN_API_KEY"
}

response = requests.request("GET", url, headers=headers)
print(response.text)
Response
HTTP/1.1 429 Too Many Requests
Retry-After: 45
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1735776060

You can use these headers to implement backoff logic in your client code.

The daily subscriber-creation limit behaves differently: instead of a 429, it returns a 400 whose body points you to POST /v1/imports as the supported way to add subscribers in bulk.