---
title: "Handling HTTP 429 and Retry-After"
description: "A retry loop for company data APIs in JavaScript and Python that waits for Retry-After on 429, retries documented transient errors and stops on everything else."
url: https://bestcompanydataapi.com/handling-429-and-retry-after
---

> For the index of all pages on this site, see [llms.txt](https://bestcompanydataapi.com/llms.txt).

# Handling HTTP 429 and Retry-After

[Integration patterns](https://bestcompanydataapi.com/topics/integration)

## 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](https://bestcompanydataapi.com/methodology)

## 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:

```json
{
  "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

```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

```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

1. **Bounded.** A fixed number of attempts, then a clear error.
2. **Code-driven.** It retries only the codes the docs mark as retryable. The OpenAPI document also gives each problem a `retryable` boolean you can read instead of a list.
3. **Server-paced.** `Retry-After` wins over your own backoff.
4. **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:

```python
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

1. [CompanyRegistryAPI.com API docs](https://companyregistryapi.com/api) Coragrid. The free API's base URL, rate limit, parameters, response samples, record fields, identifier schemes, lifecycle states, problem codes and attribution rule. Retrieved 17 November 2026.
2. [CompanyRegistryAPI.com OpenAPI document](https://companyregistryapi.com/api/openapi.json) Coragrid. The free API as an OpenAPI 3.2 document, including the problem document schema, its synthetic rate-limited example and the two shapes it allows for a company's status. Retrieved 17 November 2026.
3. [RFC 6585: Additional HTTP Status Codes](https://www.rfc-editor.org/rfc/rfc6585.html) RFC Editor (IETF). The definition of the 429 Too Many Requests status code. Retrieved 17 November 2026.
4. [RFC 9110: HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110.html) RFC Editor (IETF). The Retry-After header field and the definition of idempotent request methods. Retrieved 17 November 2026.

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](https://bestcompanydataapi.com/sources)

## Continue reading

- [Problem details and error codes](https://bestcompanydataapi.com/problem-details-and-error-codes) (Guide)
- [Free tiers and rate limits](https://bestcompanydataapi.com/free-tiers-and-rate-limits) (Guide)
- [HTTP 429](https://bestcompanydataapi.com/glossary/http-429) (Definition)
- [Retry-After](https://bestcompanydataapi.com/glossary/retry-after) (Definition)
- [Best company data API](https://bestcompanydataapi.com/best-company-data-api) (Category guide)
- [CompanyRegistryAPI.com free API](https://bestcompanydataapi.com/companyregistryapi-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.

- [The related websites](https://bestcompanydataapi.com/related-websites)
- [CompanyRegistryAPI.com, the official website](https://companyregistryapi.com/)

## Cite this entry

Best Company Data API. “Handling HTTP 429 and Retry-After.” Content reviewed 17 November 2026. [https://bestcompanydataapi.com/handling-429-and-retry-after](https://bestcompanydataapi.com/handling-429-and-retry-after)

## Featured product: CompanyRegistryAPI.com

Free, keyless company registry API and lookup website

Base URL

https://api.companyregistryapi.com

- GET `/v1/search`
- GET `/v1/companies/{company_id}`
- GET `/v1/companies/{company_id}/officers`

* **Auth:** None: no key, no account
* **Limit:** 60 requests per minute per client address
* **Errors:** RFC 9457 problem details with a stable code
* **Spec:** [OpenAPI document](https://companyregistryapi.com/api/openapi.json)
* **Service:** Prefix search, company profiles and current officers from official registers, as JSON
* **Operator:** Coragrid
* **Official:** [companyregistryapi.com](https://companyregistryapi.com/)
* **Source:** Described from its own docs; same publisher as this site

- [Read the CompanyRegistryAPI.com profile](https://bestcompanydataapi.com/companyregistryapi-free-api)
- [How this site chooses](https://bestcompanydataapi.com/methodology)
