Publishing API Limits as Specifications
Developer facts · 9 min read ·
Rate limits, quotas, payload sizes and timeouts are specifications, not surprises. How to document them for integrators and how buyers should read them.
Every public interface has limits. Some are written down and some are discovered when a script fails at two in the morning. The first kind is a specification; the second is a trap. Publishing limits as specifications is one of the cheapest ways a software team can earn trust from the people who build on its work, and one of the most commonly neglected.
This how-to guide covers what limits to document, how to describe them, how to communicate them in responses, and how a buyer can read the limits page to judge whether a product will cope with their load. It is aimed at product teams and technical writers, and written so that non-engineers can follow it.
Why limits are part of the product
An interface is a promise about what a client can do. A limit is a boundary of that promise. A customer planning to sync twenty thousand records every night needs to know whether the interface will let them. If the limit appears only after launch, they are forced into a redesign. If it is published, they can plan, or decide the product is not for them, which is also a good outcome for both sides.
Rate limiting, in general terms, is a technique for controlling the rate of requests a client may make to a service. It protects the service from overload, whether accidental or malicious, and shares capacity fairly between customers. Because it protects every customer, it is legitimate for a vendor to apply it. The only unreasonable position is to apply it in secret.
The five families of limits
Group limits into five families and document each one.
1. Rate limits
How many requests per unit of time. State:
- The unit (per second, per minute, per hour).
- The scope: per account, per user, per access token, per address.
- Whether limits differ by endpoint. Read operations are often more generous than writes.
- Whether short bursts are allowed and how large a burst can be.
If you use a token bucket or a sliding window, say so in one sentence and show a worked example. Engineers do not need the maths; they need to know what happens if they send a hundred requests at once.
2. Quotas
Total volume over a longer period, typically a month. State the quota by plan, what happens when it is reached (blocked, throttled or billed) and when it resets. Say how usage is counted: one request, one record, one unit of computation.
3. Size limits
Maximum payload size for requests and responses, maximum file size for uploads, maximum number of items in a batch, maximum length of text fields. Put these in a table. They are the limits people hit first.
4. Time limits
Request timeout, maximum duration of a background job, retention period of results, validity period of tokens and links. A client that does not know the timeout cannot choose a sensible retry strategy.
5. Concurrency limits
How many requests, connections or jobs may be in flight at once. This is distinct from rate: a client can be within its per-minute rate and still exceed concurrency by sending slow requests in parallel.
Describing each limit
Every limit entry needs the same fields. A simple template:
- Name. For example, "Requests per minute".
- Value. By plan if it varies.
- Scope. What the limit is counted against.
- Behaviour at the limit. Reject, queue, throttle or bill.
- Response. The status code and message returned.
- Reset. When the counter clears.
- Can it be raised? And how to ask.
- Last changed. A date.
Keep the values in one place. If the numbers appear in the documentation, the pricing page and a blog post, they will drift. Better to maintain a single table and link to it from everywhere else.
Telling clients in the response
A limit that is documented but invisible in use is only half useful. Good interfaces tell clients where they stand.
- Return the limit, the remaining allowance and the reset time in response headers or fields.
- When a limit is exceeded, return the standard "too many requests" status, with a clear human-readable message and a hint for how long to wait.
- Use a stable, documented error code so that clients can handle it in software without parsing text.
Document each of these in the same place as the limits. A short example of a rejected request and the right way to respond helps more than a paragraph of explanation.
Well-behaved clients back off when told to. Describe the recommended retry strategy: wait for the indicated time, then retry with a gradually increasing delay and some random variation to avoid synchronised retries from many clients.
Limits for tools that assistants call
AI assistants increasingly call products through tool protocols. The Model Context Protocol is an open standard for connecting assistants to data sources and tools. A server that exposes a product's data this way is an interface like any other, with the same need for limits. Document how many calls an assistant session may make, what the maximum result size is and whether results are truncated. An assistant that hits an undocumented cap may report a half answer as a full one, and the product will take the blame.
Reading a limits page as a buyer
If you are assessing a product for your own workload, translate its limits into your numbers.
- Estimate your peak. Not the average: the busiest minute.
- Compare it to the rate limit for the plan you would use. Leave headroom.
- Check batch sizes. If you must move many records, can you do it in batches that fit?
- Check the quota. Add up a month of use.
- Check behaviour at the limit. Blocked access during a busy period is different from a charge for extra use.
- Look for the date. An undated limits page may be out of date.
- Ask how limits change. Is there notice before reductions?
A vendor with no limits page is not a vendor with no limits. Ask for the numbers in writing.
Changing limits responsibly
Limits change as products grow. Treat a reduction as a breaking change.
- Announce reductions well in advance, in the changelog and by email to affected customers.
- Give a grace period during which clients see warnings but are not blocked.
- Where possible, offer a path to a higher limit.
- Record every change in a dated history on the limits page.
Increases are friendly changes, but still worth recording. A history is evidence that you manage the interface carefully.
A sample limits table
A compact table might include: requests per minute per access token; burst allowance; maximum records per batch; maximum request body size; request timeout; monthly quota by plan; concurrency per account; link to request an increase; date last changed. Fill in the values you can stand behind and leave nothing blank. If a limit does not exist, write "none published" and be sure that is true.
How this connects to listings and directories
If your product appears in a software directory, mention that your interface has documented limits and link to them from your listing. On this site, the developers page describes the free interface and tool server for reading listing data; its own limits are described there. Reading how another service documents its limits is a good way to calibrate how much detail to provide.
Worked example: sizing a nightly sync
Numbers make the guidance concrete. Suppose a customer wants to push a large set of records into a product every night. The limits table says that a batch may contain up to a stated number of records, that each token may send a stated number of requests per minute, and that the request timeout is thirty seconds.
The customer's engineer first divides the total records by the batch size to get the number of requests needed. Then divides that by the per-minute rate to get the minimum run time. Then checks whether that run time fits inside the overnight window, and whether any single batch could plausibly take more than the timeout to process. If the answer to any of these is no, the engineer has learned something valuable before writing any code: either to split the work across several tokens, to ask for a higher limit, or to choose a different approach such as a bulk import file.
Without a published table, the same engineer discovers the batch size by trial and error, hits the rate limit during the first full run and spends a morning reading support replies. The table is not just documentation; it is the thing that lets a project estimate be honest.
Common documentation mistakes
Only documenting the happy path. A page that lists limits but not what the error looks like leaves developers writing handling code from guesswork.
Mixing plan values into prose. "Higher plans get more" is not a specification. Put plan values in a table with one row per limit and one column per plan.
Hiding limits inside marketing pages. If the limits live only on the pricing page, developers will not find them, and the pricing page will go out of date when the documentation changes. Link instead of copying.
Treating all clients as the same. A script, a mobile app and an assistant tool call behave very differently. Where limits differ by client type, say so.
Never testing the documented behaviour. Add an automated test that sends a request over the limit and checks that the documented response is returned. Documentation that is tested stays true.
Summary
Treat limits as specifications. Document rate, quota, size, time and concurrency limits in one table, with scope, behaviour at the limit, reset and date. Tell clients where they stand in every response, give them a clear way to back off and treat reductions as breaking changes. Buyers, in turn, should translate limits into their own peak load before they commit.
Questions and answers
- What is a rate limit?
- A cap on how many requests a client may send to an interface in a given period. Requests over the cap are usually rejected with an HTTP 429 response.
- Should limits be in the documentation or the contract?
- Both are common. The documentation should state the current technical values, and the contract should state which are guaranteed and which may change with notice.
- What is the difference between a rate limit and a quota?
- A rate limit controls speed, such as requests per minute. A quota controls total volume over a longer period, such as requests per month.
- How should limits be communicated in responses?
- With headers or fields that show the limit, the amount remaining and when it resets, and a clear error with a retry hint when the limit is exceeded.