Rate Limits and Error Codes: What Happens When the API Says No

APIs break. They refuse requests. They tell you you're going too fast. They return cryptic numbers instead of the data you asked for. The difference between "it's broken, I give up" and "I know what happened and I know how to fix it" is understanding rate limits and HTTP status codes. These aren't edge cases — they're the normal operating conditions of working with APIs. If you make API calls regularly, you will hit both. The question is whether you'll know what to do when it happens.

What The Docs Say

Rate limits are documented — sometimes prominently, sometimes buried in a footnote — for every API that accepts external requests. A rate limit is a cap on how many requests you can make in a given time window. OpenAI's API limits vary by model and tier — a free-tier account might be capped at 3 requests per minute on GPT-4, while a paid account gets significantly more [VERIFY — specific tier limits change frequently, check OpenAI's rate limit documentation for current numbers]. Stripe allows 100 requests per second in live mode. Ghost's Admin API allows 100 requests per minute. The numbers vary. The concept doesn't — every API has a ceiling, and you need to know where it is before you build a workflow that hits it.

HTTP status codes are the universal language of API responses. The first digit tells you the category: 2xx means success, 3xx means redirection, 4xx means the client (you) made an error, 5xx means the server (them) had an error. The specific code tells you what happened:

• 200 — OK. Your request worked. This is the one you want.
• 201 — Created. Your request to create something worked.
• 204 — No Content. Your request worked, but there's nothing to send back (common after a DELETE).
• 400 — Bad Request. Your request was malformed. Missing a required field, wrong data type, invalid JSON.
• 401 — Unauthorized. Your API key is missing, invalid, or expired.
• 403 — Forbidden. Your key is valid, but you don't have permission for this specific action.
• 404 — Not Found. The endpoint URL doesn't exist, or the resource you asked for doesn't exist.
• 429 — Too Many Requests. You hit the rate limit.
• 500 — Internal Server Error. Something broke on their end.
• 502 — Bad Gateway. Something between you and the server broke.
• 503 — Service Unavailable. Their server is overloaded or down for maintenance.

That list covers roughly 95% of the status codes you'll encounter in practice. The remaining 5% are variations on those themes — the documentation for each API will list any specific codes they use.

What Actually Happens

Rate limits are the thing that catches people building automation workflows for the first time. Here's the scenario: you build an n8n workflow that loops through 500 contacts and makes an API call for each one. The workflow runs, processes the first 100 contacts fine, then starts returning 429 errors for every subsequent request. You didn't do anything wrong — you just sent more requests than the API allows in the time window.

The 429 response usually includes a Retry-After header that tells you — in seconds — when you can try again. Some APIs return this as a Unix timestamp instead. Either way, the API is telling you: "Slow down, wait this long, and try again." In an automation tool, this means adding delays between requests. In n8n, you can configure the HTTP Request node to wait between iterations. In Zapier, you may need to use a delay step. In a custom script, you'd implement exponential backoff — wait 1 second after the first 429, 2 seconds after the second, 4 after the third, and so on.

The "it's you vs. it's them" split is the most useful diagnostic framework for API errors. When you get a 4xx status code, the API is telling you the problem is with your request. Your job is to figure out what's wrong — check the URL, check the authentication, check the request body, check the required parameters. When you get a 5xx status code, the problem is on their end. Your job is to wait and try again later. This distinction sounds obvious, but in the moment — when your workflow is failing and you don't know why — knowing whether to debug your request or just wait is genuinely valuable.

The error response body is where the real information lives, and most people don't read it. When an API returns a 400 error, the response body typically contains a human-readable message explaining exactly what went wrong. OpenAI's API might return {"error": {"message": "you must provide a model parameter", "type": "invalid_request_error"}}. Stripe might return {"error": {"type": "card_error", "message": "Your card was declined"}}. Ghost might return {"errors": [{"message": "Resource not found", "errorType": "NotFoundError"}]}. These messages are telling you — in plain language — what happened. Read them. Literally. Before doing anything else, read the error message the API sent back.

The common patterns that trip up non-developers:

401 errors after things were working fine. Your API key expired, or you regenerated it without updating it in your automation tool. Check the key. Re-authenticate the connection. This is the most common support request for failing Zapier and n8n workflows.

400 errors when the request "looks right." Usually a data type mismatch. The API expects a number and you sent a string. Or a field name is slightly wrong — emailAddress vs. email_address. Or the JSON is malformed — a missing comma, an extra bracket. Comparing your request against the documentation example, character by character, usually reveals the problem.

404 errors on endpoints that "should exist." The API URL changed (this happens more than you'd think), you have a typo in the path, or the resource ID you're referencing doesn't exist. Double-check the URL against the current documentation, not a tutorial from 18 months ago.

Intermittent 500/502/503 errors. The server is having problems. Check the service's status page (most services have one — status.openai.com, status.stripe.com, etc.). If the status page says everything is fine but you're still getting 500 errors, the problem might be specific to your request — but that's less common. Usually 500 means wait and retry.

When To Use This

Every time an API call fails. Literally every time. The first thing you do is look at the status code — it tells you which category of problem you're dealing with. The second thing you do is read the error response body — it tells you the specifics. The third thing you do is act accordingly: fix your request (4xx), wait and retry (5xx), or slow down your request rate (429).

For automation workflows that run unattended, understanding rate limits matters at design time, not just at debug time. Before you build a workflow that makes hundreds of API calls in a loop, check the rate limits for that API. Build in appropriate delays from the start. It's much easier to add a 1-second delay between requests in your workflow design than to debug why your workflow fails at item 101 every time it runs.

The exponential backoff pattern is worth implementing in any workflow that makes API calls at scale. The concept is simple: when you get a rate limit error, wait a short time and retry. If you get another rate limit error, wait longer. Keep doubling the wait time up to some maximum. This is how well-behaved API clients operate, and most automation platforms have built-in retry mechanisms that implement this pattern — you just need to enable them.

When To Skip This

You can't really skip this. Error codes and rate limits are part of working with APIs the way traffic lights are part of driving. You can ignore them, but the consequences are immediate and obvious. The minimum viable knowledge is: 200 means it worked, 4xx means your request is wrong, 5xx means their server is broken, 429 means slow down. That's four things. Memorize those, and you can debug most API failures you'll encounter in automation work.

The deeper knowledge — specific codes, retry strategies, header inspection — becomes relevant as you build more complex workflows. But even a basic understanding of the status code system puts you ahead of the person who sees "Error 401" and assumes the service is down.

This is part of CustomClanker's API Literacy series — the thing nobody explains before you try to connect two tools.