> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topograph.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Automatic retries

> Automatic retries for outages. Self-healing for register changes. One request.

Official registers go offline. They also change. Give Topograph time to handle both and deliver the missing data through your original request.

## Built for outages. Ready for change.

![Topograph retries after temporary register outages. When a register changes, Topograph's self-healing system updates its own connection to the register and retries. Topograph delivers data through the same request.](https://mintcdn.com/semaphore/-ZYfC1Lk_wx2cKwM/images/self-healing-requests.svg?fit=max\&auto=format\&n=-ZYfC1Lk_wx2cKwM\&q=85\&s=16ae0e3cf697793c8916f2cc444f76c1)

**Topograph retries during temporary outages.** During maintenance, downtime, or rate limiting, Topograph gives the register time to recover. When it responds again, Topograph can retrieve your data on an eligible retry.

**Topograph adapts to register changes.** When a register changes its website or data format, Topograph's **self-healing system** diagnoses the problem and develops a fix for its own connection to that register.

After the fix is deployed, Topograph retries with its updated connection. Your application does not need to change or resubmit the request.

**You choose how long to wait. We handle the recovery.** Both paths keep eligible items in the original request, so your team does not need to restart the check or resubmit successful items.

A longer retry window gives the register and our self-healing system more time to restore delivery. Recovery is not guaranteed within that window; unresolved items finish with an error you can handle.

## When to use automatic retries

* **KYB checks and back-office reviews:** let temporary failures recover without sending a case back to your team or customer.
* **Scheduled and overnight verification:** give register maintenance, rate limits, and intermittent outages time to clear.
* **Incident recovery:** let an open request benefit from a fix as soon as a later retry uses it.

For a form that needs an immediate answer, use [prefill mode](https://docs.topograph.co/essentials/modes.md) instead. Automatic retries are available only in verification mode, which is the default.

## Configure your retry window

This example allows retries over a **six-hour window**. Omitting `mode` selects verification mode.

```bash theme={null}
curl --request POST \
  --url https://api.topograph.co/v2/company \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "countryCode": "FR",
    "id": "928020932",
    "dataPoints": ["company", "legalRepresentatives"],
    "maxRetryDelaySeconds": 21600
  }'
```

Choose a window that fits how long your business process can wait. These are examples, not recovery-time guarantees:

| Value | Window | Example use |
| - | - | - |
| `1800` | 30 minutes | Allow a short interruption to clear during a background check. |
| `21600` | 6 hours | Give a back-office review time for register or incident recovery. |
| `86400` | 24 hours | Let an overnight verification continue into the next day. |
| `172800` | 48 hours | Use the maximum window when your process can wait two days. |

The value must be an integer between `60` and `172800`, inclusive. Values outside this range, including `0`, are rejected with HTTP `400`.

Omit the option to keep normal retrieval behavior without an additional request-level retry window. The option cannot be added to a request after it has been created.

## Follow the original request

1. Submit the `POST` once and save the returned `request.requestId`.
2. Poll `GET /v2/company/{requestId}` or process [`company.updated` webhooks](https://docs.topograph.co/guides/webhooks). An item awaiting an automatic retry stays `in_progress`; successful items remain available and are not retrieved again.
3. Handle each item when its status becomes `succeeded` or `failed`. A webhook can contain partial results, so inspect `request.dataStatus` rather than treating the first webhook as completion of the whole request.

```bash theme={null}
curl --request GET \
  --url https://api.topograph.co/v2/company/<requestId> \
  --header 'x-api-key: <api-key>'
```

> [!WARNING]
>
> Do not submit another `POST` while an item is `in_progress`. Topograph is already handling its retries. A new `POST` creates a separate request; polling reads the current one.

See [Billing during automatic retries](https://docs.topograph.co/essentials/pricing-and-caching.md#billing-during-automatic-retries) for how the original request is settled.

## When retries run and stop

The window starts when request processing begins. It includes the initial attempt, time spent retrieving other items, and waits between attempts. Despite its name, `maxRetryDelaySeconds` is the total retry window, not the delay between attempts.

Retries wait until all items in the current attempt have finished. The delay increases between attempts and includes a random variation to spread out traffic. The schedule depends on the window and the error; there is no fixed interval or guaranteed number of attempts.

A deployment makes a fix available to subsequent attempts. It does not force an immediate retry or extend your chosen window.

The window limits when another attempt can start. It does not cancel an attempt already running or guarantee that the request finishes within that time. A slow initial attempt can consume the entire window without leaving time for a retry.

Once no further retry is scheduled, an unsuccessful item becomes `failed` with its error details. An ineligible failure can become `failed` before the window ends. A successful item is returned as soon as it is available.

## Which failures qualify

Only errors marked `retryable: true` can qualify, and that flag alone does not guarantee an automatic retry. For document retrieval and other operations that can place a register order, Topograph retries only when it can confirm no order was submitted. An uncertain outcome is reported as `failed` rather than risking a duplicate order.

Permanent errors such as `resource_not_found`, `no_data_available`, and `invalid_request` are not retried. Neither are `graph`, the legacy `companyProfile` datapoint, or [manually delivered](https://docs.topograph.co/essentials/manual-delivery.md) items.

The option is available only in verification mode. Combining it with `mode: "prefill"`, `X-Topograph-No-Cache`, or `agenticEnrichment` is rejected with HTTP `400`.

> [!NOTE]
>
> Request manual items separately when you want automatic items to retry promptly. A manual item can take days and delay the next attempt for other items in the same request, consuming their retry window.

## After a final failure

`maxRetryDelaySeconds` and `retryAfterSeconds` serve different purposes:

| Field | Where it appears | What it controls |
| - | - | - |
| `maxRetryDelaySeconds` | Your `POST /v2/company` body | How long Topograph may keep scheduling eligible retries within this request. |
| `error.retryAfterSeconds` | A failed item's response | How long to wait before you submit a new request for that item. |

If an item ultimately fails with `retryAfterSeconds: 300`, wait at least another 5 minutes before [resubmitting it](https://docs.topograph.co/guides/reliability-and-errors.md#retrying-a-retryable-item). The response field does not define the automatic retry schedule or extend the original window.

Check [status.topograph.co](https://status.topograph.co/) for an ongoing incident. For the full list of error codes and how to handle them, see [Reliability & Errors](https://docs.topograph.co/guides/reliability-and-errors.md#datapoint-and-document-error-codes).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.