Bug: Incorrect 429 limit

[debok]

Affected Product
Which product does this bug affect?

API

Describe the bug

I'm infrequently receiving a 429 error from the API that reports a limit of 10 instead of 100. For example, "429: Too Many Requests: Rate limit exceeded: 24 of 10 requests per 20 seconds". Most API requests are successful.

To Reproduce

For a church with over 30,000 people, quickly make API requests to the people endpoint, traversing the entire list of people. You'll need to back off on requests before you hit regular limits. See rough code below:

def calculate_wait(headers)
  count = headers['x-pco-api-request-rate-count']
  limit = headers['x-pco-api-request-rate-limit']
  period = headers['x-pco-api-request-rate-period']
  Rails.logger.info("count: #{count}, limit: #{limit}, period: #{period}") # for trouble-shooting

  (count / limit.to_f) < 0.8 ? 0 : period.to_i
end

offset = 0
loop do
  response = api_client.people(offset: offset, per_page: 100)
  # wait so as to not run into API limits
  sleep(calculate_wait(response.headers))

  offset += 100
  break if response.body['data'].empty?
end

Expected behavior

The API should not return 429 errors unless the x-pco-api-request-rate-count is greater than or equal to 100.

Screenshots

Additional Context:

• Endpoint: people/v2/people
• Language: Ruby on Rails
• Authentication: OAuth 2

Additional context

This error only appeared in the last 4 days or so.

I have..

• Reviewed the documentation found at https://developer.planning.center/docs
• Searched for previous issues reporting this bug
• Removed all private information from this issue (credentials, tokens, emails, phone numbers, etc.)
• Reviewed my issue for completeness

[github-actions]

Potentially Related Issues

I found some existing issues that may be related to this one. Please check if any of them address your question before waiting for a response:

🟣 #1428 — Internal Server Error 500 - reading large number of people. (Closed)

Summary: User experienced intermittent 500 Internal Server Errors when paginating through a large People dataset (30,000+ records) at around offset 5,200. This relates to the new issue as both involve problems when making many sequential requests to the People API for large organizations, though one experiences 429 errors with incorrect limits and the other experienced 500 errors.

Key discussion points:

• The issue occurred when fetching people in batches of 50-100 with proper rate limiting delays (250ms between requests)
• Error occurred consistently around the 5,200 person offset mark when traversing a 30,000+ person dataset
• User implemented retry logic for both 429 (rate limiting) and 500 (internal server) errors
• CSV export was suggested as an alternative for bulk data retrieval of large datasets

Resolution: Shane Bonham from Planning Center identified that the errors coincided with a system incident on Tuesday between 7:05-7:20 AM Pacific (documented on status.planningcenter.com). The user confirmed they were able to successfully complete the import after the incident was resolved, suggesting it was a temporary infrastructure issue rather than a code or API design problem. The issue was closed as resolved with no ongoing problems.

---

This comment was generated automatically. If none of these match your issue, no action is needed — a team member will review your issue soon.

[gkemmey]

hi @debok,

rate limits can be dynamic and might vary based on the endpoint or request details. our recommendation is to rely on the rate-limit headers in the response, which will let your application automatically handle any limit changes (up or down).

https://api.planningcenteronline.com/docs/overview/rate-limiting

in addition to managing the count, limit, and period, a good second layer of defense is to handle any 429 responses by waiting for the duration specified in the retry-after header before retrying. for example, we could add a 429 check to your loop:

response = api_client.people(offset: offset, per_page: 100)

if response.status == 429
  sleep(response.headers['retry-after'].to_i)
  next
end

sleep(calculate_wait(response.headers))

we're also rolling out improved bucketing that should keep those headers more consistent as you paginate through collections.