How to Announce an API Rate Limit Change in English
Learn how to write a clear, professional announcement when changing API rate limits — communicating new thresholds, the reasoning, and migration guidance to developer customers.
Changing API rate limits — tightening them to protect infrastructure, or restructuring them into new tiers — directly affects every developer integrated with your platform. A poorly communicated rate limit change generates a flood of confused support tickets and broken integrations; a well-communicated one gives developers time to adapt and reduces churn. This guide covers the English for announcing the change clearly.
Key Vocabulary
Rate limit — the maximum number of requests a client can make within a given time window, after which further requests are rejected or throttled. “The new rate limit is 100 requests per minute per API key, down from the previous unlimited tier during our beta period.”
Throttling — slowing down or delaying requests once a client approaches a limit, as opposed to outright rejecting them. “Rather than immediately rejecting requests once you hit the limit, we throttle them with increasing delay — you’ll see slower responses before you see errors.”
429 Too Many Requests — the standard HTTP status code returned when a client exceeds its rate limit.
“Once you exceed the new threshold, requests will return a 429 Too Many Requests status instead of the previous 200 OK.”
Rate limit headers — response headers (like X-RateLimit-Remaining and X-RateLimit-Reset) that tell a client how many requests they have left and when the limit resets.
“We’re adding rate limit headers to every response so your integration can proactively back off before hitting the limit, rather than discovering it via errors.”
Grace period — a window of time where the old, more permissive limit still applies, giving developers time to adjust before enforcement begins. “There’s a 30-day grace period where we’ll log violations of the new limit without enforcing it, so you can monitor your usage before it becomes a hard block.”
Structuring the Announcement
- What’s changing: “Starting [date], the rate limit for the
/searchendpoint will change from 1,000 requests per hour to 300 requests per hour.” - Why: “This change is necessary to keep the platform stable for all customers — a small number of integrations were consuming a disproportionate share of capacity.”
- Who’s affected: “This affects all API keys on the Free and Pro tiers. Enterprise tier customers are not affected by this change.”
- What to do: “If your integration currently exceeds 300 requests per hour, we recommend batching requests or caching responses where possible. See our migration guide for specific patterns.”
- Timeline: “The grace period begins [date] and enforcement begins [date] — you have four weeks to adjust before the new limit is enforced.”
Handling Developer Pushback
- “I understand this is a significant change for high-volume integrations — we’re happy to discuss a custom limit for your use case if the standard tier doesn’t fit your needs.”
- “This wasn’t a decision we made lightly — the previous limits were causing degraded performance for the majority of customers during peak hours.”
- “If the new limit is blocking a critical use case, please reach out directly and we’ll work with you on a short-term exception while you adjust your integration.”
Providing Migration Guidance
- “The most common fix we’ve seen is caching responses for data that doesn’t change frequently — many integrations were re-fetching the same data on every request.”
- “Consider using our webhook events instead of polling — this eliminates the need for frequent requests entirely for most use cases.”
- “If you’re batching multiple lookups, our new bulk endpoint accepts up to 100 IDs per request, counting as a single request against your rate limit.”
Professional Tips
- Give real notice, not a same-day surprise. A grace period, even a short one, dramatically reduces the number of angry support tickets you’ll get.
- Explain the “why” briefly but honestly. Developers are far more forgiving of a rate limit change when they understand it’s protecting overall platform stability, not an arbitrary restriction.
- Offer a path, not just a restriction. Pairing the announcement with concrete migration guidance turns a frustrating change into a solvable problem.
Practice Exercise
- Write a two-sentence summary announcing a rate limit reduction from 1,000 to 300 requests per hour, including the effective date.
- Draft a response to a developer asking for an exception because the new limit breaks their integration.
- Write one migration tip for a developer whose integration polls the same endpoint every few seconds.