APIs and Rate Limits in Plain Terms
An API is an agreement about how two programs talk. A rate limit is the part of that agreement that says how often. Understanding both prevents the most common beginner mishaps.
An agreement, not a mystery
An application programming interface, or API, is a defined way for one piece of software to ask another to do something. On the web this usually means your program sends a request to an address and receives a structured reply. The API's documentation is the contract: which addresses exist, what you must send, what comes back, and what the service promises not to change without warning.
Thinking of it as a contract is useful because it tells you where to look when something fails. Either you did not follow the contract, or the service did not, and the first is far more common.
The parts of a request
A typical web request has a method that says what kind of action you want, an address that says what you want it done to, headers that carry extra details such as who you are, and sometimes a body containing data. The reply carries a status code, headers of its own, and usually a body. Learn to look at all of these, not only the body. Much of what you need for debugging is in the status code and the headers.
Status codes sort themselves into families
Status codes are grouped by their first digit. Codes beginning with two mean the request succeeded. Codes beginning with four mean the service thinks you made a mistake: a malformed request, missing credentials, or a resource that does not exist. Codes beginning with five mean the service itself failed. This split tells you whose turn it is to act. With a four, change your request before sending it again. With a five, the same request may work later.
Why limits exist
A public service is shared. If one client sends requests as fast as its loop can run, it uses capacity that everyone else needs. Rate limiting is how a service protects itself and its other users: it allows each client a certain number of requests in a period of time and refuses the rest. The refusal normally arrives with the status code 429, which means too many requests.
The limit is part of the contract. It is usually described in the documentation, and many services also report it in the response headers, telling you how many requests you have left and when the allowance resets. Read those headers. They are the service telling you exactly how to behave.
What to do when you are refused
The wrong response is to retry immediately in a tight loop, which makes the situation worse and can get your access suspended. The right response is to wait. If the reply says how long to wait, wait that long. If it does not, wait a short time, and if the next attempt also fails, wait longer, increasing the delay after each failure. This approach is called exponential backoff. Adding a little randomness to each delay helps when many clients are retrying at once, so that they do not all return at the same instant.
Give up eventually. A program that retries forever is a program that hangs forever. Set a maximum number of attempts and report a clear error when it is reached.
Ask for less
The best way to stay under a limit is to make fewer requests. Three habits help.
- Cache. If you asked for something a moment ago and it is unlikely to have changed, keep the answer and reuse it.
- Batch. If the API lets you ask for many items in one request, do that instead of asking for each separately.
- Page deliberately. Long lists usually arrive in pages. Fetch the pages you need, not every page by reflex.
Develop against saved replies
While writing your program, you will run it dozens of times. If each run calls the real service, you can use up an allowance without having achieved anything. Save a few real replies to files early on, and have your program read those while you work on the logic. Switch to the live service once the handling is right. Your development becomes faster as well, because reading a file is quicker than waiting on a network.
Timeouts and partial failure
Networks fail in dull ways: a request can simply never be answered. Always set a timeout, so that your program gives up on a silent connection instead of waiting indefinitely. And remember that a request can succeed on the server while its reply is lost on the way back. For actions that change something, check the documentation for how to retry safely without doing the action twice.
Be a polite client
Identify your program honestly where the API asks you to, follow the published terms, and do not look for ways around a limit. Limits are rarely personal. A client that behaves predictably and backs off when asked is one a service can afford to keep serving.
Working rule: a four means fix the request, a five means try later, and a 429 means slow down. Never retry faster than you were just told to.
Last revised 2026-11-20 · Wendell Arkwright