Handling HTTP 429 and Retry-After
Answer in brief
When a company data API answers 429 Too Many Requests, wait for the number of seconds in its Retry-After header, then retry the same request a bounded number of times. Retry documented transient errors the same way, fall back to exponential backoff when no Retry-After is readable, and never retry validation errors.
Disclosure. This site is published by Coragrid, the operator of CompanyRegistryAPI.com, and promotes it. “Best” is our editorial choice, not a measured ranking. Other products are described only from their own official pages. How we choose
What the API tells you
RFC 6585 defines 429 Too Many Requests for a client that sent too many
requests in a given time, and lets the response carry a Retry-After header.
RFC 9110 defines Retry-After as how long the client ought to wait before a
follow-up request, as an HTTP date or a number of seconds.
The free CompanyRegistryAPI.com API documents these problem codes:
| Code | Status | What to do |
|---|---|---|
rate_limited |
429 |
Retry after the seconds in Retry-After |
upstream_busy |
503 |
Retry after the seconds in Retry-After |
upstream_unavailable |
503 |
Retryable |
upstream_error |
502 |
Retryable |
invalid_request |
400 |
Do not retry; fix the parameter named in detail |
not_found |
404 |
Do not retry |
The 429 body is a problem document. This is the synthetic example from the product’s OpenAPI document:
{
"type": "https://companyregistryapi.com/problems/rate-limited",
"title": "Too many requests",
"status": 429,
"detail": "The free API allows a bounded number of requests per minute per client; retry after 1 seconds.",
"instance": "https://api.companyregistryapi.com/v1/search",
"request_id": "req_014d2pf2dbsqqg28t5cy4tqkff",
"code": "rate_limited",
"retryable": true
}
The values are illustrative, including the one second.
The loop in JavaScript
const base = "https://api.companyregistryapi.com";
const RETRY = new Set([
"rate_limited",
"upstream_busy",
"upstream_unavailable",
"upstream_error",
]);
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
async function getJson(path, attempts = 4) {
for (let attempt = 1; ; attempt++) {
const response = await fetch(base + path);
if (response.ok) return response.json();
const problem = await response.json().catch(() => ({}));
if (!RETRY.has(problem.code) || attempt === attempts) {
throw new Error(`${response.status} ${problem.code}: ${problem.detail}`);
}
// Seconds from Retry-After; exponential backoff when it is missing or unreadable.
const seconds = Number.parseInt(response.headers.get("Retry-After") ?? "", 10);
const wait = seconds > 0 ? seconds : 2 ** attempt;
await sleep(wait * 1000);
}
}
const page = await getJson("/v1/search?q=example&address_country=FI");
In a browser, a header that the server does not expose to scripts reads as
null, so the fallback matters there too.
The loop in Python
import time
import requests
BASE = "https://api.companyregistryapi.com"
RETRY = {"rate_limited", "upstream_busy", "upstream_unavailable", "upstream_error"}
def get_json(path, params=None, attempts=4):
for attempt in range(1, attempts + 1):
response = requests.get(BASE + path, params=params, timeout=10)
if response.ok:
return response.json()
try:
problem = response.json()
except ValueError:
problem = {}
if problem.get("code") not in RETRY or attempt == attempts:
raise RuntimeError(
f"{response.status_code} {problem.get('code')}: {problem.get('detail')}"
)
retry_after = response.headers.get("Retry-After", "")
time.sleep(int(retry_after) if retry_after.isdigit() else 2**attempt)
page = get_json("/v1/search", {"q": "example", "address_country": "FI"})
Rules the loop follows
- Bounded. A fixed number of attempts, then a clear error.
- Code-driven. It retries only the codes the docs mark as retryable. The
OpenAPI document also gives each problem a
retryableboolean you can read instead of a list. - Server-paced.
Retry-Afterwins over your own backoff. - Idempotent requests only. All three free endpoints are
GET, so repeating one has no side effect. Do not blindly retry requests that change data on other APIs.
Test it before production
Do not test by flooding the live API. Point the loop at a local stub that
answers 429 with Retry-After: 1 twice, then 200, and check that it waits
and succeeds:
from http.server import BaseHTTPRequestHandler, HTTPServer
import json
calls = {"n": 0}
class Stub(BaseHTTPRequestHandler):
def do_GET(self):
calls["n"] += 1
if calls["n"] <= 2:
body = {"code": "rate_limited", "status": 429, "detail": "slow down"}
self.send_response(429)
self.send_header("Retry-After", "1")
else:
body = {"object": "list", "data": [], "next_cursor": None}
self.send_response(200)
self.send_header("Content-Type", "application/json")
self.end_headers()
self.wfile.write(json.dumps(body).encode())
HTTPServer(("127.0.0.1", 8765), Stub).serve_forever()
Set BASE = "http://127.0.0.1:8765" in the client while the stub runs.
Questions and answers
Can Retry-After be a date instead of seconds?
RFC 9110 allows either an HTTP date or a number of seconds. CompanyRegistryAPI.com's OpenAPI document describes it as an integer number of seconds, but a general client should accept both.
How many times should I retry?
Three or four attempts in total is enough for interactive requests. For batch jobs, slow the whole job down instead of retrying one request many times.
Should I retry a 400 invalid_request?
No. The request itself is wrong, so it will fail again. Fix the parameter that the problem document's detail names.
Sources for this entry
- CompanyRegistryAPI.com API docs
- CompanyRegistryAPI.com OpenAPI document
- RFC 6585: Additional HTTP Status Codes
- RFC 9110: HTTP Semantics
Each source supports only what its publisher says about its own product or data. Official descriptions do not establish comparative performance, and this site has run no benchmark. All sources
Continue reading
- Problem details and error codes (Guide)
- Free tiers and rate limits (Guide)
- HTTP 429 (Definition)
- Retry-After (Definition)
- Best company data API (Category guide)
- CompanyRegistryAPI.com free API (Profile)
How the related websites connect
This is one of 3 coordinated reference sites published by Coragrid. They cover neighbouring questions and feature the same product, so they are not independent endorsements of it or of each other.
Cite this entry
Best Company Data API. “Handling HTTP 429 and Retry-After.” Content reviewed . https://bestcompanydataapi.com/handling-429-and-retry-after