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 which is growing rapidly. If this rate limit is causing problems, please reach out to support so we can form an audit on your account and lift the limit.

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.