ThisCalculator

Everyday

Rate Limits & Retries: Search API Guide

Updated · Standard formula, shown below

This guide explains how to handle rate limits and implement retries when calling a search results API. You’ll learn the standard HTTP status codes to watch for, how to respect the Retry-After header, and how to build a retry loop that avoids hammering the server. By the end, you’ll have a robust strategy that keeps your app responsive and your API key in good standing.

What You’ll Need

  • An API key or access token for the search API you’re using.
  • A basic understanding of HTTP requests and responses (status codes, headers).
  • Your programming language of choice (examples here are language-agnostic, with pseudocode).
  • Access to the API’s documentation to confirm its specific rate limit rules.

Step-by-Step

  1. Read the API documentation for rate limits. Most search APIs specify a maximum number of requests per minute, hour, or day. They may also define a quota based on tokens or credits. Note the exact numbers and the time window (e.g., 100 requests per minute).
  2. Check every response for rate limit headers. Many APIs include headers like X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Log these values if possible. If the headers are absent, rely on the HTTP status code (see next step).
  3. Handle HTTP 429 (Too Many Requests). When you get a 429, the server is telling you to slow down. Do not retry immediately. Look for a Retry-After header in the response. It may be a number of seconds (e.g., Retry-After: 30) or a HTTP-date (e.g., Retry-After: Wed, 21 Oct 2025 07:28:00 GMT). If the header is missing, use a default backoff (e.g., 1 second, then double each attempt).
  4. Implement exponential backoff with jitter. For retries, don’t use a fixed delay. Start with a short wait (e.g., 1 second), then double it on each retry (1s, 2s, 4s, 8s…). Add a random jitter (e.g., ±20%) to prevent synchronized retries from multiple clients. Cap the maximum delay (e.g., 60 seconds) to avoid excessive waiting.
  5. Set a maximum number of retries. Decide how many times you’ll retry before giving up. A common pattern is 3 to 5 retries. After that, fail gracefully: return a clear error to the user or log the failure for later analysis.
  6. Respect the Retry-After header when present. If the API sends a specific delay, always use that value instead of your exponential backoff. It’s the server’s official recommendation for when it will be ready.
  7. Handle other retriable status codes. Besides 429, also consider retrying on 500 (Internal Server Error), 502 (Bad Gateway), 503 (Service Unavailable), and 504 (Gateway Timeout). These are often transient. Do not retry on 400 (Bad Request) or 401 (Unauthorized) — those indicate a problem with your request that won’t change.
  8. Use a queue or throttle for non-urgent requests. If you have many requests to make, consider adding a simple delay between requests (e.g., 50ms) to stay under the limit. For bursty workloads, a token bucket algorithm can smooth out the rate.
  9. Log and monitor. Track how often you hit rate limits and how many retries you use. This helps you adjust your concurrency or request patterns. If you’re consistently hitting limits, you may need to request a higher quota or reduce your request frequency.
  10. Test your retry logic. Simulate a 429 response to ensure your code waits and retries correctly. Many APIs have sandbox modes; otherwise, you can mock the HTTP response in your tests.

Common Mistakes

  • Retrying immediately on 429. This makes the problem worse and can get you temporarily banned. Always wait at least the Retry-After value.
  • Ignoring the Retry-After header. Using your own backoff when the server gives a specific time is wasteful and may cause more 429s.
  • Retrying on client errors (4xx). A 400 or 401 won’t succeed on retry; you’re just wasting requests.
  • No maximum retry count. Infinite retries can hang your application forever. Always set a limit.
  • Using a fixed delay for all retries. This can cause thundering herd problems if many clients retry simultaneously.
  • Not checking rate limit headers before sending. If you know you’re at zero remaining, wait instead of sending a request that will fail.

Tips

  • Cache results. If you’re searching for the same query often, cache the response locally to reduce API calls.
  • Use conditional requests. Some APIs support ETags or If-Modified-Since headers to avoid re-sending full responses when nothing changed.
  • Batch requests if the API supports it. Some search APIs allow multiple queries in one call, which counts as one request.
  • Consider using a library. Many HTTP clients have built-in retry support (e.g., Python’s requests with urllib3 Retry, or Node.js axios-retry). Use them to avoid reinventing the wheel.
  • Set a timeout on your HTTP requests. This prevents your app from hanging if the server is slow. A typical timeout is 10-30 seconds.
  • Store the rate limit reset time. If you get a 429 with a reset time, you can schedule your next request to happen exactly after that time, rather than polling.

Troubleshooting

  • You’re still getting 429 after implementing backoff. Check if your API key is shared across multiple services. You might be exceeding the limit collectively. Also verify that you’re not accidentally running multiple instances of your app. Consider using a distributed lock or a central rate limiter.
  • The Retry-After header is missing. Fall back to your exponential backoff. If the API documentation doesn’t specify a default, use a starting delay of 1-2 seconds.
  • Your retries are not working. Ensure you’re reading the status code correctly. Some APIs return 200 with an error body instead of a 4xx/5xx. Check the response body for error flags.
  • You’re hitting limits on the first request. This suggests your API key is already over quota or the limit is very low. Check your usage dashboard on the API provider’s site. You may need to wait for the reset period.
  • Retries are causing duplicate side effects. For search APIs, this is usually not an issue since searches are read-only. But if you’re also making write requests, ensure your retry logic is idempotent (e.g., include a request ID).

Frequently Asked Questions

What is the difference between rate limiting and throttling?

Rate limiting is the server’s way of saying “you’ve sent too many requests, slow down” (HTTP 429). Throttling is a client-side technique where you deliberately slow down your request rate to stay under the limit. Both aim to prevent overloading the server.

Should I retry on every 5xx error?

Generally yes, but with caution. 500 and 503 are often transient. 501 (Not Implemented) and 505 (HTTP Version Not Supported) are not retriable. Always cap your retries and use backoff to avoid making a server outage worse.

How do I know what the rate limit is if the API doesn’t document it?

You can test empirically: send requests until you get a 429, then note the time window. However, this is risky and may get you temporarily banned. Better to contact the API provider or look for community documentation.

Can I use a single API key for multiple users?

Usually yes, but the rate limit applies to the key, not the user. If you have many users, you’ll hit the limit quickly. Consider using a backend proxy that caches results and manages the key centrally.

What is jitter and why is it important?

Jitter is a random delay added to your backoff time. Without it, if many clients retry at the same time, they’ll all wait the same amount and then hit the server simultaneously, causing another wave of 429s. Jitter spreads out the retries.

Is it better to wait for the rate limit reset or use backoff?

If the API provides a reset time (via headers or the 429 body), wait for that exact time. If not, exponential backoff is a good heuristic. For long waits, consider queuing the request and processing it later.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.